REST API 규칙

REST API(Representational State Transfer API)

구성

1. 자원(RESOURCE) - URI

2. 행위(Verb) - HTTP METHOD

3. 표현(Representations)

REST API 디자인 가이드

REST API 설계시 가장 중요한 항목 2가지 : URI, HTTP Method

1. URI는 정보의 자원을 표현해야 한다. 

 - 리소스명은 동사보다는 명사를 사용

 - 좋지 않은 예 : GET /members/delete/1 
   --> delete와 같은 행위에 대한 표현이 들어가서는 안됨

 - 좋은 예 : DELETE /members/1

2. 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE 등)로 표현

 - GET /members/delete/1 (X) ------> DELETE /members/1

 - 예: 회원정보를 가져오는 URI

   GOOD - GET /members/1

   BAD - GET /members/show/1

 - 예 : 회원정보를 추가하는 URI

   GOOD - POST /members/2

   BAD - GET /members/insert/2

[참고] HTTP METHOD의 알맞은 역할 

1. POST : POST를 통해 해당 URI를 요청하면 리소스를 생성함 

2. GET : GET를 통해 해당 리소스를 조회. 해당 도큐먼트에 대한 상세 정보 가져오기

3. PUT : PUT를 통해 해당 리소스를 수정함

4. DELETE : DELETE를 통해 리소스를 삭제함

[URI 설계 시 주의할 점]

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

 - 예 : houses/apartmemts, animals/mamals

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

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

 - URI를 쉽게 읽고 해석하기 위해, 불가피하게 긴 URI 경로를 사용하게 된다면 하이픈을 사용해 가독성을 높일 수 있음

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

 - 밑줄은 보기 어려울 수 있으므로 '_' 대신 '-' 사용

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

 - 대문자 사용은 되도록 피하기. 대소문자에 따라 다른 리소스로 인식하게 되기 때문

6. 파일 확장자는 URI에 포함하지 않음

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

1. /리소스명/리소스 ID/관계가 있는 다른 리소스명

 - 예 : GET /users/{userid}/devices ---> 일반적으로 소유 'has'의 관계를 표현할 때

2. 만약 관계명이 복잡하다면 이를 서브 리소스에 명시적으로 표현

 - 예 : 사용자가 '좋아하는' 디바이스 목록 표현

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

[HTTP 응답 상태 코드]

1-1. 200 : 클라이언트의 요청을 정상적으로 수행함

1-2. 201 : 클라이언트가 어떠한 리소스를 요청, 해당 리소스가 성공적으로 생성됨(POST 작업시)

2-1. 400 : 클라이언트의 요청이 부적절한 경우

2-2. 401 : 클라이언트가 인증되지 않은 상태에서 보호된 리소스를 요청했을 때 사용하는 응답 코드

                 (로그인 하지 않은 유저가 로그인 했을 때, 요청 가능한 리소스를 요청했을 때)

2-3. 403 : 유저 인증상태와 관계없이 응답하고 싶지 않은 리소스를 클라이언트가 요청했을 때 사용하는 응답 코드 

2-4. 405 : 클라이언트가 요청한 리소스에서는 사용 불가능한 Method를 이용했을 경우 사용하는 응답 코드

3-1. 301 : 클라이언트가 요청한 리소스에 대한 URI가 변경되었을 때 사용하는 응답코드

3-2. 500 : 서버에 문제가 있을 시 사용하는 응답 코드 

출처

REST API 제대로 알고 사용하기 : NHN Cloud Meetup