📌 설계 중심 규칙
URI는 정보의 자원을 표현해야 한다
자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE 등)으로 표현한다
URI 작성 규칙
👎
GET /users/show/1👍
GET /users/1URI는 자원을 표현해야 하므로, show와 같은 행위가 포함되면 안된다. show는 HTTP Method인 GET을 통해 충분히 표현 가능하다.
자원은 Collection과 Element로 나누어 표현할 수 있고, 아래 테이블에 기초하여 서버 대부분과의 통신 행태를 표현할 수 있다.
PATCH vs PUT
PUT은 해당 자원의 전체를 교체한다는 의미
PATCH는 일부를 변경한다는 의미
→ update 이벤트에서 PUT보다 의미적으로 더 적합하다는 평가
마지막에 / 를 포함하지 않는다.
👎
GET /users/1/👍
GET /users/1_(underbar) 대신 -(dash) 를 사용한다.
👎
POST /users/post_comments👍
POST /users/post-comments소문자를 사용한다
👎
POST /users/postComments👍
POST /users/post-comments컨트롤 자원을 의미하는 URI 예외적으로 동사를 허용한다.
함수처럼, 컨트롤 자원을 나타내는 URL은 동작을 포함하여 명명한다.
👎
POST /posts/duplicating👍
POST /posts/duplicateHTTP Status
성공 응답은 2XX 로 응답한다
-
200 : OK
-
201 : CREATED
- 200과 달리 요청에 성공하고, 새로운 리소스를 만든 경우에 응답
- POST, PUT
- 200과 달리 요청에 성공하고, 새로운 리소스를 만든 경우에 응답
-
202 : ACCEPTED
-
클라이언트 요청을 받은 후, 요청은 유효하지만 서버가 아직 처리하지 않은 경우
- 비동기 작업
- 요청에 대한 응답이 일정 시간 후 완료되는 작업인 경우
- 작업 완료 후 클라이언트에 알릴 수 있는 server push 작업을 하거나, 클라이언트가 해당 작업의 진행 상황을 조회할 수 있는 URI 응답해야함
HTTP/1.1 202 Accepted { "links": [ { "rel": "self", "method": "GET", "href": "https://api.test.com/v1/users/3" } ] }
-
-
204 : NO Content
- 응답 body가 필요없는 자원 삭제 요청(DELETE) 같은 경우
- 200 응답 후 null, {}, [], false를 return 하는 것과 다르다. 아예 HTTP Body가 없음
실패 응답은 4XX로 응답한다
-
400 : [Bad Request]
-
클라이언트 요청이 미리 정의된 파라미터 요구사항을 위반한 경우
-
파라미터의 위치(
path,query,body), 사용자 입력 값, 에러 이유 등을 반드시 알린다- case 1
{ "message" : "'name'(body) must be Number, input 'name': test123" }- case 2
{ "errors": [ { "location": "body", "param": "name", "value": "test123", "msg": "must be Number" } ] }
-
-
401 : [Unauthorized]
-
403 : [Forbidden]
- 해당 요청은 유효하나 서버 작업 중 접근이 허용되지 않은 자원을 조회하려는 경우
- 접근 권한이 전체가 아닌 일부만 허용되어 요청자의 접근이 불가한 자원에 접근 시도한 경우 응답한다.
-
404 : [Not Found]
-
405 : [Method Not Allowed]
- 405 code는 404 code와 혼동될 수 있기 때문에 룰을 잘 정하고 시작한다.
POST /users/1의 경우 404로 응답한다고 생각할 수 있지만, 경우에 따라 405로 응답할 수 있다./users/:idURL은 GET, PATCH, DELETE method는 허용되고 POST는 불가한 URL이다.- 만약 id가
1인 사용자가 없는 경우엔 404로 응답하지만(GET, PATCH, DELETE의 경우),POST /users/1는/users/:idURL이 POST method를 제공하지 않기 때문에 405로 응답하는 게 옳다.
- 만약 id가
Allow: GET, PATCH, DELETEHTTP header에 허용 가능한 method를 표시한다.
-
409 : [Conflict]
-
해당 요청의 처리가 비지니스 로직상 불가능하거나 모순이 생긴 경우
-
e.g.)
DELETE /users/hak의 경우, 비지니스 로직상 사용자의 모든 자원이 비어있을 때만 사용자를 삭제할 수 있는 규칙이 있을 때 409로 응답한다.409 Conflict { "message" : "first, delete connected resources." "links": [ { "rel": "posts.delete", "method": "DELETE", "href": "https://api.test.com/v1/users/hak/posts" }, { "rel": "comments.delete", "method": "DELETE", "href": "https://api.test.com/v1/users/hak/comments" } ] }
-
-
429 : [Too Many Requests]
Retry-After: 3600(HTTP Headers)- DoS, Brute-force attack 같은 비정상적인 접근을 막기 위해 요청의 수를 제한한다.
입력 Form 형태
새로운 Item 작성하거나 기존의 Item을 수정하는 경우, 작성/수정 Form은 어떻게 제공해야 할까?
→ Form 자체로도 정보로 취급
모바일 환경에 따라 다른 정보를 보여야 하는 경우
REST API는 URI가 플랫폼 중립적이어야 하기 때문에, Request Header의 User-Agent 값을 참조하는 것이 좋다.
아이폰에서의 User-Agent>
Mozilla/5.0 (iPhone; U; CPU like Mac OS X; en) AppleWebKit/420+ (KHTML, like Gecko) Version/3.0 Mobile/1A543a Safari/419.3출처