API, Rest, Restful, Rest API, Restful API 개념&차이

Aurora·2025년 2월 26일

API

1. API란?

API (Application Programming Interface)

소프트웨어 간에 데이터·기능을 상호 교환할 수 있게 해주는 인터페이스
하나의 프로그램(혹은 서비스)이 다른 프로그램(혹은 서비스)에게 “이렇게 요청해 주세요. 그럼 이 응답을 드릴게요.” 라고 약속(명세)을 미리 정해둔 것

특징

명세(Specification)
- “특정 URL로 이렇게 요청을 하면, 어떤 형태의 응답을 돌려주겠다”와 같은 규칙이 명시되어 있음.
응용 프로그램 간 소통
- 프론트엔드 <-> 백엔드
- 서로 다른 회사 시스템 간의 연동(결제, 소셜 로그인 등)
- 모바일 앱 <-> 서버 등등이 모두 API를 통해 이뤄짐.
문서화
- API를 잘 쓰려면 해당 API의 사용 방법(파라미터, 응답 형식 등)을 이해해야 하기 때문에 문서화가 중요

비유

식당에서 손님은 주방(내부 기능)에 직접 들어가지 않고, 메뉴판(API 문서)을 보고 주문

주방(서비스 내부)은 메뉴판(API 명세)에 따라 음식을 만들어서 손님에게 제공(응답)

2. REST란?

REST (Representational State Transfer) : 표현(json등)형식으로 상태(자원내용) 전송

2000년대 초반, 로이 필딩(Roy Fielding)의 박사 논문에서 제안된 아키텍처 스타일
HTTP 프로토콜의 특징을 극대화하여 확장성과 호환성을 높이는 웹 서비스 디자인 원칙

REST의 주요 특징

클라이언트-서버 구조 (Client-Server)
- UI/UX(클라이언트)와 데이터 저장/처리(서버)를 분리.
무상태성 (Stateless)
- 서버가 클라이언트의 상태를 보관하지 않음.
- 요청 간 공유 정보가 최소화되어, 수평 확장(Scale-out)이 쉽고, 서버간 부담이 줄어듦.
캐시 가능 (Cacheable)
- HTTP 캐시 가능성을 활용해, 리소스 요청의 중복을 줄임.
계층화 (Layered System)
- 중간 계층(프록시, 게이트웨이 등)을 자유롭게 넣어도 시스템이 동작.
- 각 계층은 자신이 맡은 역할만 수행, 클라이언트는 이를 몰라도 됨.
인터페이스 일관성 (Uniform Interface)
- HTTP 메서드(GET, POST, PUT, DELETE, …)와 URI(자원 식별) 사용을 명확히 함
- 자원(URI), 행위(HTTP 메서드), 표현(Representation: JSON, XML 등)을 나누어 설계.

한 줄 정의

“REST” = HTTP를 활용한 웹 서비스 설계를 할 때,

“URI로 자원을 식별하고,

HTTP 메서드로 그 자원을 조회/생성/수정/삭제하며,

서버는 무상태로 동작한다.”
라는 원칙(스타일).

3. RESTful이란?

“RESTful”은 형용사. REST의 원칙을 충실히 지키고 있는(준수하는) 상태
예:
- URI에 명사를 사용해 자원을 표현 (/users/1, /orders/12 등),
- 요청에 맞게 HTTP 메서드를 구분해서 쓰는 것(조회는 GET, 생성을 POST, 수정은 PUT/PATCH, 삭제는 DELETE),
- 요청과 응답에서 JSON(혹은 XML 등 동일한 포맷)을 사용하는 것 등이 잘 지켜지면 Restful한 것.

추가 내용

실제 프로젝트에서 모든 REST 원칙을 100% 지키는 것은 어려움.

예를 들어, POST /users/delete/1처럼 메서드가 실제 의도와 불일치한다면 완벽하게 RESTful하다고 볼 수 없음.

따라서 “RESTful”이란 상대적인 개념이며, 얼마나 REST 원칙을 준수하고 있는지를 나타내는 척도라고 생각하면 됨.

4. REST API와 RESTful API

4.1 REST API

REST 아키텍처 스타일을 기반으로 구현된 API
- HTTP URI로 리소스를 식별하고, HTTP 메서드로 자원을 조작
예) GET /users/1 → ID가 1인 User 조회
POST /users → 새 User 생성
일반적인 실무에선, REST 원칙 중 일부라도 따르고 있으면 “REST API”라고 부르는 경우가 많다고 함.

4.2 RESTful API

“REST API 중에서도 REST의 여러 제약(원칙)을 더 엄격하게 지킨 API”
이 때, 그 "엄격하게 지킨다"의 기준은 팀별 내 규정에 따름.
예)
- 자원 경로(URI) 명칭이 명확하고,
- HTTP 메서드를 의도에 맞게 정확히 구분,
- HTTP 상태 코드(200, 201, 404, 500 등)를 의미에 맞게 반환,
- HATEOAS 등 심화된 REST 개념 적용
  → 이런 요소들을 제대로 지켰다면 “RESTful API”라고 말할 수 있음

참고 : HATEOAS란?

HATEOAS(Hypermedia as the Engine of Application State)
- Hypermedia: 하이퍼링크가 포함된 문서(HTML, JSON, XML 등) 자체를 의미
REST 아키텍처 스타일에서 권장되는 제약(Constraint) 중 하나
하이퍼미디어(Hypermedia)를 애플리케이션 상태 전이(이동)의 엔진으로 사용한다는 개념
HATEOAS: 서버가 응답에 하이퍼링크(URI 정보)를 함께 보내, 클라이언트가 다음 액션(상태 전이)을 링크를 통해 동적으로 결정하도록 하는 방식
-> 이렇게 서버가 응답 안에 “현재 리소스와 관련된 링크들”을 담아줌으로써 클라이언트는 서버의 응답을 통해 “다음에 어떤 URI로 요청할 수 있는지”를 직접 알 수 있게 됨.

예시 : 사용자 리소스 조회 응답 (JSON)

{
  "id": 123,
  "name": "Alice",
  "email": "alice@example.com",
  "links": {
    "self": {
      "href": "https://api.example.com/users/123",
      "method": "GET"
    },
    "update": {
      "href": "https://api.example.com/users/123",
      "method": "PUT"
    },
    "delete": {
      "href": "https://api.example.com/users/123",
      "method": "DELETE"
    },
    "friends": {
      "href": "https://api.example.com/users/123/friends",
      "method": "GET"
    }
  }
}

재밌다. 다음엔 HATEOAS에 대해 더 알아보고 이 방식으로 프로젝트를 진행해 보자.

결론

REST API: REST 스타일을 어느 정도 반영해 만든 HTTP 기반 API

RESTful API: REST의 개념을 더 충실히 (혹은 이상적으로) 구현한 API

5. 전체적인 차이점 & 공통점

항목	정의	예시	기타
API	소프트웨어 간 기능·데이터를 교환하기 위한 인터페이스	Java의 JDBC, Android SDK, 웹 API(트위터, 구글지도 등)	내부 라이브러리 API, 운영체제 API, 외부 서비스 API 등 다양
REST	웹 서비스 아키텍처 스타일 (개념·원칙)	무상태성, 자원·행위 분리, HTTP 메서드 & URI	구현체가 아닌 “설계 지침”이나 “철학”에 가까움
RESTful	REST 원칙을 잘 따르고 있는 상태(형용사)	예쁜(일관된) URI, 적절한 메서드·상태코드 사용, 무상태성 유지	상대적 개념(완벽하게 지키는지 정도의 차이 있음)
REST API	REST 스타일 기반으로 구현된 API	`GET /users`, `POST /users` 등 HTTP 요청	보통 “REST API = HTTP + JSON”처럼 많이 사용됨
RESTful API	REST API 중에서도 REST를 제대로 (엄격히) 구현한 API	자원 식별(URI), 상태 유지 없음, HATEOAS 적용 등 더 완벽한 설계	REST API와 거의 유사하나, “얼마나 이상적으로?”의 강조 차이

공통점은..
모두 웹(혹은 소프트웨어) 상에서 데이터 교환을 다루는 핵심 개념들! 이라고 할 수 있는 듯 하다.

6. 비유와 예시

6.1 식당 비유

API:
- 식당의 메뉴판. 손님은 메뉴판에 적힌 방식을 따라 주문하고, 식당은 그에 맞춰 음식을 제공
REST:
- 식당 운영의 방침(인테리어, 주방 동선, 주문 시스템 등)를 효율적으로 만들어 놓은 가이드라인.
RESTful:
- 그 운영 가이드라인을 정말 잘 준수하고 있는 식당.
- (예: 깔끔한 메뉴판, 메뉴명과 실제 음식이 정확히 일치, 추가 요청 사항도 명확히 정리, 주문-제조-서빙 프로세스가 딱딱 맞음 등)
REST API:
- “메뉴판(인터페이스)”을 REST 방식으로 설계한 것.
- 메뉴판에 각 음식(자원)이 명확한 URL로 표시되고, 주문 행위(HTTP 메서드)가 구분되어 있음.
RESTful API:
- “메뉴판 설계, 주문 절차, 서빙 과정” 모든 부분이 REST 가이드라인에 완벽히 부합.
- 손님은 메뉴를 정확히 보고, 원하는 것만 바로 요청 가능. 음식 제공 흐름이 매끄럽고 효율적.

6.2 도서관 비유

API:
- “책을 빌리고(수정), 폐기(삭제), 찾아보기(조회)” 기능을 사서에게(시스템에게) 요청하는 규칙.
REST:
- 도서관에서 자료를 정리, 검색, 대출하는데 매우 효율적인 아키텍처 설계(가이드).
RESTful:
- 도서관이 그 설계를 아주 충실히 지켜서, 찾기도 쉽고, 반납도 간단하고, 줄 서거나 기다릴 필요가 거의 없는 상태.
REST API:
- “책의 자원(URI)” + “행위(HTTP 메서드)” 형식으로 도서관 기능을 제공.
- 예: GET /books/123 → 123번 책 정보, POST /books → 새로운 책 등록
RESTful API:
- 검색, 대출, 반납 등 모든 자원과 행위가 일관되게 정리되고, HTTP 상태코드(예: 200, 404)도 정확히 사용.
- 새 책이 등록됐으면 201 Created를 주는 등 좋은 설계를 따름.

7. 프로젝트 기획&개발 시 고려사항

API 문서화
- 어떤 요청(HTTP 메서드, URI, 파라미터)을 보내면 어떤 응답(Body, 상태 코드)을 받는지 명확히 작성.
- 예: Swagger, Postman, GitBook 등
URI 설계
- 자원 단위로 설계(명사 사용), 복수형 권장 (예: /users, /orders)
- 행동(행위)은 HTTP 메서드로 구분 (조회: GET, 생성: POST, 수정: PUT/PATCH, 삭제: DELETE 등)
- 가능하다면, /users/add처럼 URI에 동사를 넣지 말기!
HTTP 메서드 & 상태 코드
- 의도에 맞는 메서드 사용 (새 자원 등록은 POST, 전체 수정은 PUT, 부분 수정은 PATCH)
- 상태 코드도 의미 맞추기 (성공시 200 OK, 생성시 201 Created, 잘못된 요청 400 Bad Request, 권한 문제 403 Forbidden, 리소스 없음 404 Not Found 등)
무상태성(Stateless)
- 세션이나 쿠키로 상태를 너무 많이 저장하면 서버 확장 시 복잡해짐.
- JWT(Token) 기반 인증 등으로 상태 최소화.
보안 & 인증
- 민감 정보는 HTTPS로 암호화, Authorization 헤더로 토큰(OAuth, JWT 등) 전달.
- API 키, 클라이언트 인증서 등 다양한 방식 고려.
버전 관리
- 변경사항이 생길 경우 /v1/→ /v2/ 형태로 버전을 URI나 헤더에 명시할 수 있음.

결론

RESTful한 API를 잘 만들면, 클라이언트/서버 간 협업이 명확해지고, 시스템 확장도 수월해진다! 잘 쓰자

8. 정리

API:
- 소프트웨어가 기능(로직)·데이터를 교환하기 위한 인터페이스
- 식당의 “메뉴판” 개념
REST:
- HTTP 활용에 대한 아키텍처 철학/원칙 (자원·행위·표현 분리, 무상태성 등)
RESTful:
- 그 원칙을 잘 지키고 있는(혹은 가까운) 상태(형용사)
REST API:
- REST 아키텍처를 바탕으로 만들어진 HTTP 기반 API
RESTful API:
- REST API 중에서도 REST 원칙을 더 엄격하고 일관성 있게 적용한 것

Aurora

개발에 애정을 쏟는 연구자입니다

이전 포스트

네트워크 관련 핵심정리

다음 포스트