슬래시 구분자(/)는 계층 관계를 나타내는 데 사용한다
포워드 슬래시(/)는 경로path 내에서 리소스 간의 계층 관계를 나타내는 데 사용한다. 예를 들면 다음과 같다.
http://api.canvas.restapi.org/shapes/polygons/squares
URI 마지막 문자로 슬래시(/)를 포함하지 않는다
http://api.canvas.restapi.org/shapes/ (x)
http://api.canvas.restapi.org/shapes (o)
규칙을 엄격하게 적용하지 않은 API들은 클라이언트가 보낸 URI를 마지막에 슬래시(/)가 없는 URI로 리다이렉트하기도 한다.
즉, 클라이언트에서 URI 맨 뒤에 슬래시(/)를 붙이더라도 오류로 처리하지 않고 슬래시(/)가 없는 URI로 전용한다
URI 경로에는 소문자가 적합하다
URI 경로에 대문자를 사용하면 문제가 될 수 있으므로 소문자를 사용한다.
http://api.example.restapi.org/my-folder/my-doc ➊
HTTP://API.EXAMPLE.RESTAPI.ORG/my-folder/my-doc ➋
http://api.example.restapi.org/My-Folder/my-doc ➌
①은 괜찮다.
②는 URI 포맷 스펙(RFC 3986)에서 ①과 같은 것으로 간주한다.
③은 ①, ②와는 다른 URI다. 대소문자를 섞어 사용하게 되면 때로 혼란을 일으킬 수 있다.
파일 확장자는 URI에 포함시키지 않는다
http://api.college.restapi.org/students/transcripts/2005/fall.json ➊
http://api.college.restapi.org/students/transcripts/2005/fall ➋
① 파일 확장자를 포맷을 나타내는 용도로 사용해서는 안 된다.
② REST API 클라이언트에서 권장하는 방법은 HTTP에서 제공하는 포맷 선택 메 커니즘을 이용하는 것이다.
API에 있어서 서브 도메인은 일관성 있게 사용해야 한다
API 최상위 도메인과 1차 서브 도메인 이름(예, soccer.restapi.org)으로 서비스 제공자를 식별해야 한다. API의 전체 도메인 이름에 api라는 서브 도메인을 다음과 같이 붙여야 한다.
http://api.soccer.restapi.org
도큐먼트 이름으로는 단수 명사를 사용해야 한다
도큐먼트 리소스를 나타내는 URI는 단수 명사나 명사구를 포함하는 경로 부분으로 이름을 짓는다. 예를 들면, 한 명의 선수 도큐먼트를 나타내는 URI는 단수 형태가 되어야 한다
http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet/players/claudio
* 도큐먼트 : 이 책에서 도큐먼트라 함은 객체 인스턴스나 데이터베이스 레코드와 유사한 단일 개념이다
컬렉션 이름으로는 복수 명사를 사용해야 한다
컬렉션을 식별하는 URI는 복수 명사나 복수 명사구를 나타내는 명사로 경로의 이름을 지어야 한다. 그리고 컬렉션 이름은 균일하게 포함되도록 선택해야 한다. 예를 들어, 선수 도큐먼트의 컬렉션 URI는 포함된 리소스의 복수 명사 형태로 나타낸다.
http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet/players
경로 부분 중 변하는 부분은 유일한 값으로 대체한다
http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet/players/21 ➊
http://api.soccer.restapi.org/games/3fd65a60-cb8b-11e0-9572-0800200c9a66 ➋
① 21이라는 값이 playerId를 대체하고 있다.
② UUID 값이 gameId를 대체하고 있다.
REST API의 클라이언트에서는 URI가 하나의 유의미한 리소스 식별자임을 고려해야 한다. 백엔드 시스템의 식별자(이를 테면, 데이터베이스의 ID와 같은)가 URI 경로에 표시될 수 있지만, 이는 클라이언트 코드 입장에서는 별로 의미가 없다. URI를 유일한 ID로 사용해야만 기존 클라이언트에 영향을 미치지 않고, REST API의 백엔드 시스템을 개선할 수 있다.
CRUD 기능을 나타내는 것은 URI에 사용하지 않는다
DELETE /users/1234 ( O )
GET /deleteUser?id=1234 ( X )
GET /deleteUser/1234 ( X )
DELETE /deleteUser/1234 ( X )
POST /users/1234/delete ( X )
CRUD 기능을 나타내는 것은 URI에 사용하지 않는다
DELETE /users/1234 ( O )
GET /deleteUser?id=1234 ( X )
GET /deleteUser/1234 ( X )
DELETE /deleteUser/1234 ( X )
POST /users/1234/delete ( X )
GET 메서드는 리소스의 상태 표현을 얻는 데 사용해야 한다
웹은 구조상 GET 메서드의 특성에 많이 의존한다. 클라이언트에서 GET 요청을 반복해도 문제가 없어야 하며, 캐시는 리소스를 제공하는 원래 서버와 통신하지 않고도 캐시된 내용을 제공할 수 있어야 한다.
PUT 메서드는 리소스를 삽입하거나 저장된 리소스를 갱신하는 데 사용해야 한다
PUT 메서드는 클라이언트가 기술한 URI로 스토어에 새로운 리소스를 추가하는 데 사용한다. 이미 스토어에 저장된 리소스를 갱신하거나 다른 것으로 대체하는 데도 PUT 메서드를 사용한다.
POST 메서드는 컬렉션에 새로운 리소스를 만드는 데 사용해야 한다
클라이언트는 POST 메서드를 사용해서 컬렉션 안에 새로운 리소스를 만든다.
POST 요청 바디는 새로운 리소스를 위해 제안된 상태 표현을 포함하는데, 이것은 서버 소유의 컬렉션에 추가된다.
POST 메서드는 컬렉션에 새로운 리소스를 만드는 데 사용해야 한다
클라이언트는 DELETE 메서드 요청을 사용하여 컬렉션이나 스토어인 부모에서 리소스를 완전히 제거한다.
주어진 리소스에 DELETE 요청이 수행되면, 클라이언트는 그 리소스를 볼 수 없게 된다. 따라서 GET 메서드나 HEAD 메서드로 리소스의 현재 상태를 가져오려는 어떤 API 시도도 404(“Not Found”) 상태로 끝나게 된다
200(“OK”)는 일반적인 요청 성공을 나타내는 데 사용해야 한다
200은 클라이언트가 요청한 어떤 액션이었든지 REST API가 성공적으로 수행했음을 나타내는 코드로, 클라이언트는 이 코드를 받길 원한다. 또한 더 이상의 할당된 '2xx'계열의 응답코드가 없다는 뜻이기도 하다. 204 상태 코드와는 달리, 200 응답은 응답 바디가 포함된다
200(“OK”)는 응답 바디에 에러를 전송하는 데 사용해서는 안 된다
항상 이 부분에 기술한 규칙을 사용하여 적절한 HTTP 응답 상태 코드를 사용한다. 특히, REST API는 부실한 HTTP 클라이언트에 부합하려는 그 어떤 타협도 해서는 안 된다
201(“Created”)는 성공적으로 리소스를 생성했을 때 사용해야 한다
REST API는 클라이언트의 요청으로 새로운 리소스를 이용하여 컬렉션에 생성했거나 스토어에 추가했을 때 201 상태 코드로 응답한다. 컨트롤러의 행동으로 새로운 리소스가 생겨났을 경우에도 201 상태 코드로 응답한다.
202(“Accepted”)는 비동기 처리가 성공적으로 시작되었음을 알릴 때 사용해야 한다
202 응답은 클라이언트의 요청이 비동기적으로 처리될 것임을 나타낸다. 이 응답상태 코드는 유효한 요청이었지만, 최종적으로 처리되기까지는 문제가 생길 수도 있다는 것을 클라이언트에게 알려준다. 보통 202 응답은 처리 시간이 오래 걸리는 액션에 사용된다. 컨트롤러 리소스는 202 응답을 보낼 수 있지만 다른 리소스 타입은 보낼 수 없다.
204(“No Content”)는 응답 바디에 의도적으로 아무것도 포함하지 않을 때 사용한다
204 상태 코드는 보통 PUT, POST, DELETE 요청에 대한 응답으로 이용하는데, REST API가 응답 메시지의 바디에 어떠한 상태 메시지나 표현을 포함해서 보내지 않을 때 사용한다. API는 GET 요청에 204로 응답할 수 있는데, 요청된 리소스는 존재하나 바디에 포함시킬 어떠한 상태 표현도 가지고 있지 않다는 것을 나타낸다.
301(“Moved Permanently”)는 리소스를 이동시켰을 때 사용한다
301 상태 코드는 REST API 리소스 모델이 상당 부분 재설계되었거나 계속 사용할 새로운 URI를 클라이언트가 요청한 리소스에 할당하였다는 것을 나타낸다. REST API는 응답의 Location 헤더에 새로운 URI를 기술해야 한다.
303(“See Other”)은 다른 URI를 참조하라고 알려줄 때 사용한다
보내는 대신, 응답 리소스의 URI를 보냈음을 나타낸다. 이것은 임시 상태 메시지의 URI일 수도 있고, 이미 존재하는 영구적인 리소스의 URI일 수도 있다.
303 상태 코드는 일반적으로 REST API가 클라이언트에 상태 다운로드를 강요하지 않으면서 참조 리소스를 보내는 것을 허용한다. 대신 클라이언트는 응답 Location 헤더에 있는 값으로 GET 요청을 보낼 수 있다
307(“Temporary Redirect”)는 클라이언트가 다른 URI로 요청을 다시 보내게 할 때 사용해야 한다
HTTP/1.1은 최초의 302(“Found”) 상태 코드 의미를 반복하기 위해 307 응답 코드를 도입하였다. 307 응답은 REST API가 클라이언트의 요청을 처리하지 않을 것임을 나타낸다. 클라이언트는 응답 메시지의 Location 헤더에 기술된 URI로 요청을 다시 보내야 한다. REST API는 요청된 클라이언트의 리소스에 임시 URI를 할당하여 상태 코드를 사용할 수 있다. 예를 들면, 307 응답은 클라이언트 요청을 다른 호스트로 바꾸는 데 사용한다.
400(“Bad Request”)는 일반적인 요청 실패에 사용해야 한다
400은 다른 적절한 ‘4xx’ 오류 값이 없을 때 사용하는 일반적인 클라이언트의 에러 상태다.
401(“Unauthorized”)는 클라이언트 인증에 문제가 있을 때 사용해야 한다
401 오류 응답은 클라이언트가 적절한 인증 없이 보호된 리소스를 사용하려고 할 때 발생한다. 인증을 잘못하거나 아예 인증하지 못할 경우 발생한다.
403(“Forbidden”)은 인증 상태에 상관없이 액세스를 금지할 때 사용해야 한다
403 오류 응답은 클라이언트의 요청은 정상이지만, REST API가 요청에 응하지 않는 경우를 나타낸다. 즉, 403 응답은 클라이언트의 인증에 문제가 있어서 발생하는 것이 아니다. 만약 클라이언트 인증 자체에 문제가 있다면 401(“Unauthorized”)를 사용한다.
404(“Not Found”)는 요청 URI에 해당하는 리소스가 없을 때 사용해야 한다
404 오류 상태 코드는 말그대로 클라이언트가 요청한 URI에 해당하는 리소스가 존재하지 않을 때 사용한다.
405(“Method Not Allowed”)는 HTTP 메서드가 지원되지 않을 때 사용해야 한다
클라이언트가 허용되지 않은 HTTP 메서드를 사용하려 할 때, API는 405 오류 응답을 한다. 읽기 전용 리소스는 GET 메서드와 HEAD 메서드만 지원하며, 컨트롤러 리소스는 PUT 메서드와 DELETE 메서드를 제외한 GET 메서드와 POST 메서드만 허용할 것이다.
405 응답에는 Allow 헤더가 포함되어야 하며, 그 값으로 리소스가 지원하는 HTTP 메서드를 다음 예와 같이 나타내야 한다.
- Allow: GET, POST
406(”Not Acceptable”)은 요청된 리소스 미디어 타입을 제공하지 못할 때 사용해야 한다
406 오류 응답은 클라이언트의 Accept 요청 헤더에 있는 미디어 타입 중 해당하는 것을 만들지 못할 때 발생한다. 예를 들어, API가 json(application/json) 데이터 포맷만 지원한다면, xml (application/xml) 포맷 데이터를 요청한 클라이언트는 406 응답을 받는다.
409(“Conflict”)는 리소스 상태에 위반되는 행위를 했을 때 사용해야 한다
409 오류 응답은 클라이언트 요청에 의해 REST API 리소스가 불가능 또는 모순상태가 될 수 있는 경우에 사용한다. 예를 들어, 클라이언트가 비어 있는 스토어 리소스를 삭제하라고 요청하면, REST API에서 이 응답 오류를 보낸다.
412(“Precondition Failed”)는 조건부 연산을 지원할 때 사용한다
412 오류 응답은 특정한 조건이 만족될 때만 요청이 수행되도록 REST API로 알려준다. 클라이언트가 요청 헤더에 하나 이상의 전제 조건을 지정할 경우 발생하며, 이러한 조건이 만족되지 않으면 412 응답은 요청을 수행하는 대신에 이 상태 코드를 보낸다.
415(“Unsupported Media Type”)은 요청의 페이로드에 있는 미디 어 타입이 처리되지 못했을 때 사용해야 한다
415 오류 응답은 요청 헤더의 Content-Type에 기술한 클라이언트가 제공한 미 디어 타입을 처리하지 못할 때 발생한다. 예를 들어, API가 json(application/ json)으로 포맷된 데이터만 처리할 수 있을 때, 클라이언트가 xml(application/ xml)로 포맷된 데이터로 요청하면 415 응답을 받는다.
500(“Internal Server Error”)는 API가 잘못 작동할 때 사용해야 한다
500은 일반적인 REST API 오류 응답이다. 웹 프레임워크는 대부분 예외 사항을 발생시키는 요청 핸들러 코드가 실행될 경우 자동적으로 이 응답 코드를 발생시킨 다. 500 오류는 클라이언트의 잘못으로 발생한 것이 아니기 때문에, 클라이언트가 이 응답을 발생시킨 것과 같은 요청을 다시 시도하면 다른 응답을 받을 수도 있다.