REST API 디자인 가이드

REST API 디자인 가이드

---

1. URI는 정보의 자원을 표현해야 한다.
2. 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)로 표현한다.

중심 규칙

---

사용자 추가, 삭제, 수정을 하는 REST API를 설계해보자.
URI는 정보의 자원을 표현해야 한다. (리소스는 명사를 선호)

GET /members/delete/1

아이디가 1인 계정을 삭제하라는 뜻 같다. 이것은 REST 할까?
REST하지 않다. URI는 자원을 표현하는데 중점을 두어야 하며, delete같은 행위에 대한 표현이 들어가면 안된다.
위의 URI는 아래와 같이 수정할 수 있다.

DELETE /members/1

HTTP Method

그렇다면 회원을 추가하거나 정보를 조회하는 것을 설계해 보자.

회원정보 조회

GET /members/1 (o)
GET /members/get/1 (x)

회원 추가

POST /members/2 (o)
GET /members/add/2 (x)

URI는 자원을 표현하는데 집중하고,
HTTP METHOD는 자원의 행위를 정의하자!!

주의할점

---

1. 슬래시 구분자(/)는 계층 관계를 나타내는 데 사용

   http://testapi.example.com/houses/apartments
   http://restapi.example.com/animals/mammals/whales

2. URI 마지막 문자로 슬래시(/)를 포함하지 않는다.

3. 하이픈(-)은 URI의 가독성을 높이는데 사용한다.

4. 밑줄(_)은 URI에 사용하지 않는다.

5. URI경로에는 소문자가 적합하다.

6. 파일확장자는 URI에 포함시키지 않는다.
   REST API에서는 메시지 바디 내용의 포멧을 나타내기 위해 파일 확장자를 URI 안에 포함시키지 않는다.
   Accept 헤더를 사용하여 이용한다.

    http://restapi.example.com/house/image/front.jpg (x)
    GET / house/image/front HTTP/1.1 HOST : restapi.example.com Accept : image/jpg

리소스 간의 관계를 표현하는 방법

---

REST 리소스 간에는 연관 관계가 있을 수 있고, 이런 경우 다음과 같은 표현방법을 사용한다.

/리소스명/리소스 ID/관계가 있는 다른 리소스명
GET : /users/{userid}/devices (has 관계)

만약에 관계명이 복잡하다면 이를 서브 리소스에 명시적으로 표현하는 방법이 있습니다. 예를 들어 사용자가 ‘좋아하는’ 디바이스 목록을 표현해야 할 경우 다음과 같은 형태로 사용될 수 있다.

GET : /users/{userid}/likes/devices (관계명이 애매하거나 구체적 표현이 필요할 때)

자원을 표현하는 Collection과 Document

---

Document - 문서, 객체
Collection - Documnet의 집합

Collection과 Document 모두 리소스라고 표현할 수 있으며 URI로 표현가능 하다.

http://restapi.example.com/sports/soccer

sports 라는 컬렉션과 soccer라는 도큐먼트로 표현되 있다고 생각하면 된다.

http://restapi.example.com/sports/soccer/players/13

sports, players 컬렉션과 soccer, 13 (13번 선수) 도큐먼트로 URI가 이루어져 있다.
URI를 설계할 때 컬렉션은 복수로, 도큐먼트는 단수로 사용한다.

출처 : https://meetup.toast.com/posts/92