Restful 설계 원칙

- 이번 글에서는 Restful 설계 원칙에 대해서 다뤄보겠습니다.

 

1) URL Rules

(1) 마지막에 / 포함하지 않는다

 Bad

http://api.test.com/users/

Good

http://api.test.com/users

 

(2) _(언더바) 대신 -(대시)를 사용한다

- 단, -(대시)의 사용도 최소한으로 설계한다 

Bad

http://api.test.com/users/post_comments

Good

http://api.test.com/users/post-comments

(3) 소문자를 사용한다

Bad

http://api.test.com/users/postComments

Good

http://api.test.com/users/post-comments

(4) 행위(method)는 URL에 포함하지 않는다.

Bad

POST http://api.test.com/users/1/delete-post/1

Good

http://api.test.com/users/1/posts/1

(5) 컨트롤 자원을 의미하는 URL은 예외적으로 동사를 허용한다.

- 함수처럼 컨트롤 리소스를 나타내는 URL은 동작을 포함하는 이름을 짓는다.

 

 

2) Set HTTP Headers

(1) Content-Location

- POST 요청은 대부분 idempotent 하지 않다. 

  즉, 반환되는 응답 리소스의 결과가 항상 동일하지는 않다.

POST /users
{
	"name": "hak"
}

- 위와 같은 요청은 매번 다른 리소스를 반환한다.

   첫번째는 /users/1, 두번째는 /users/2, ... n번째는 /users/n

   따라서 요청의 응답 헤더에 새로 생성된 리소스를 식별할 수 있는 Content-Location 속성을 이용한다. 

HTTP/1.1 200 OK
Content-Location: /users/1

- 반면, GET, PUT 등의 요청은 idempotent 하다. 

 

- 이 때, HATEOAS로 Content-Location을 대체할 수 있다. 

 

(2) Content-Type

- application/json을 우선적으로 제공한다. 

 

(3) Retry-After

- 비정상적인 방법(ex)DoS, Brute-force attack)으로 API 서버를 이용하려는 경우, 429 Too Many Requests 오류 응답과 함께 일정 시간 뒤 요청할 것을 나타낸다.

HTTP/1.1 429 Too Many Requests
Retry-After: 3600

(3-1) Case 1. 인증

- /auth : Oauth, JWT 같은 인증 관련 리소스를 요청하는 작업

- /login: Id, Password를 이용한 로그인 작업

 

- 비정상적인 요청(401)일 때, 두 가지 응답 방안이 있습니다.

(1) n 시간 동안 n회만 요청 가능한 경우

- 429 응답과 함께 Retry-After: n

(2) n 회만 요청 가능한 경우

- 401 응답과 함께 해당 IP는 더 이상 인증 관련 API를 사용할 수 없고, 다시 요청하려면 특수한 절차가 필요하다고 응답

 

(3-2) Case 2. 자원 요청

- /posts : 특정 사용자가 의도적으로 서버 과부하를 목적으로 반복 요청하는 경우

(1) n 시간 동안 n회 이상 요청한 경우

- 429 응답

 

참고

RESTful API 설계 가이드 (tistory.com)