REST API란 무엇인가요?

자원의 이름으로 구분하여 해당 자원의 상태(정보)를 주고 받는 것을 의미한다. REST API는 HTTP 프로토콜을 의도에 맞게 디자인 하도록 유도하고 있다.

즉, REST는 HTTP를 기반으로 클라이언트가 서버의 리소스에 접근하는 방식을 규정한 아키텍처이고 REST API는 REST를 기반으로 서비스 API를 구현한 것이다.

REST API의 구성

  • 자원 : 모든 자원에는 고유한 ID가 존재하고 ID는 /store/:store_ID와 같은 HTTP URI이다.
  • 행위 : 자원에 대한 행위 (HTTP 요청 메서드)
  • 표현 : 자원에 대한 행위의 구체적 내용 (페이로드, JSON)

REST API 설계 규칙

1. URI는 리소스를 표현하는데 집중하고 마지막에 슬래시 포함하지 않는다.

1
2
3
4
5
6
7
# bad
GET /getTodos/1
GET /todos/show/1
GET /todos/1/

# good
GET /todos/1

2. 행위에 대한 정의는 HTTP 요청 메서드를 통해 정의한다.

HTTP 요청 메서드 종류 목적 페이로드
GET index/retrieve 모든/특정 리소스 취득 X
POST create 리소스 생성 O
PUT replace 리소스 전체 교체 O
PATCH modify 리소스 일부 수정 O
DELETE delete 모든/특정 리소스 삭제 X
  • 리소스에 대한 행위는 HTTP 요청 메서드를 통해 표현하며 URI에 표현하지 않는다.
1
2
3
4
5
# bad
GET /todos/delete/1

# good
DELETE /todos/1

3. 슬래시 구분자(/)는 계층 관계를 표현

1
http://example.com/stores/restaurant

4. 불가피하게 긴 URI인 경우 하이픈(-) 사용

1
http://example.com/stores/very-long-store

단 밑줄(_)은 포함하지 않는다.

5. 파일 확장자는 URI에 포함하지 않는다.

1
2
3
4
5
# bad
http://example.com/stores/restaurant/:1/logo.png

# good
GET /stores/restaurant/:1/logo HTTP/1.1 HOST: example.com Accept: image/png
  • 대신 Accept header를 사용한다.

RESTful한 REST API 설계하기

RESTful은 이해하기 쉽고 사용하기 쉬운 REST API를 만들고, 일관적인 컨벤션을 통해 API의 이해도를 높이는 것을 말한다.

REST API 설계 예시

CRUD HTTP verbs Route
resource 목록 표시 GET /resource
resource 하나 내용 표시 GET /resource/:id
resource 생성 POST /resource
resource 수정 PUT /resource/:id
resource 삭제 DELETE /resource/:id

응답상태 코드

상태코드 설명
1xx 전송 프로토콜 수준의 정보 교환
2xx 클라이언트 요청 성공
3xx 클라이언트 요청 완료하기 위해 추가 행동 필요
4xx 클라이언트의 잘못된 요청
5xx 서버쪽 오류