요청 메서드
- 클라이언트는 상호작용 하려는 메서드를 HTTP 요청 메시지의 Request-Line 부분에 명시한다.
- RFC 2616에서는 Request-Line 문법을 다음과 같이 정의함
- Request-Line = Method SP Request-URI SP HTTP-Version CRLF (SP: Space, CRLF: Carriage Return Line Feed)
- GET : 리소스 상태의 표현을 얻을 때 사용
- HEAD : 리소스 상태에 대한 메타데이터를 얻을 때 사용
- PUT : 새로운 리소스를 스토어에 추가하거나 기존 리소스 갱신
- DELETE : 부모에서 리소스를 제거
- POST : 컬렉션에 새로운 리소스를 만들거나 컨트롤러를 실행할 때 사용함
규칙
GET 메서드나 POST 메서드를 사용하여 다른 요청 메서드를 처리해서는 안 된다
한정된 HTTP 문법으로 클라이언트에 대응하기 위해서 HTTP 요청 메서드를 원래의 의미와 다르게 사용하는 REST API를 설계해서는 안 된다
GET 메서드는 리소스의 상태 표현을 얻는 데 사용해야 함
- 웹은 구조상 GET 메서드의 특성에 많이 의존함
- 클라이언트에서 GET 요청을 반복해도 문제가 없어야 하며, 캐시는 리소스를 제공하는 원래 서버와 통신하지 않고도 캐시된 내용을 제공할 수 있어야 함
응답 헤더를 가져올 때는 반드시 HEAD 메서드를 사용해야 한다
- HEAD 메서드는 GET 메서드와 동일한 응답을 주지만 바디가 없다
- 클라이언트는 HEAD 메서드를 사용하여 리소스 존재 여부를 확인하거나 메타데이터만 읽을 수 있음
PUT 메서드는 리소스를 삽입하거나 저장된 리소스를 갱신하는 데 사용해야 한다
- PUT 메서드는 클라이언트가 기술한 URI로 스토어에 새로운 리소스를 추가하는 데 사용
- 이미 스토어에 저장된 리소스를 갱신하거나 다른 것으로 대체하는 데도 PUT 메서드 사용
- PUT 요청 메시지의 바디에 포함된 리소스의 표현이 GET 요청을 통해서 받는 리소스에 대한 표현과 같지 않을 수 있음(변경되는 부분만 표현하는 것을 허용할 수 있음)
PUT 메서드는 변경 가능한 리소스를 갱신하는 데 사용해야 한다
PUT 요청 메시지에는 원하는 형태로 변경된 메시지 바디를 포함할 수 있다
위의 규칙과 다른 점은 위의 규칙은 갱신이고 이 규칙은 아예 형태 자체를 변경하는 것을 포함하는 것같음
POST 메서드는 컬렉션에 새로운 리소스를 만드는 데 사용해야 한다
POST 요청 바디는 새로운 리소스를 위해 제안된 상태 표현을 포함하는데, 이것은 서버 소유의 컬렉션에 추가된다
POST 메서드는 컨트롤러를 실행하는 데 사용해야 한다
- HTTP 표준에서는 POST 메서드에 의미상의 제한을 두지 않으며, 반복이나 부작용과 상관없이 어떤 액션도 수행할 수 있다. 이런 특징 때문에 POST 메서드를 제한 없는 컨트롤러 리소스로 사용할 수 있다
- REST API 디자인은 컨트롤러 리소스로 모든 동작을 실행하기 위해 POST 메서드를 사용하는데, 각 기능 및 동작은 직관적으로 HTTP 메서드들과 매핑되지 않음
DELETE 메서드는 그 부모에서 리소스를 삭제하는 데 사용해야 한다
- 클라이언트는 DELETE 메서드 요청을 사용하여 컬렉션이나 스토어인 부모에서 리소스를 완전히 제거함
- GET 메서드나 HEAD 메서드로 DELETE 된 리소스에 대해 요청하게 되면 404(”Not Found”)로 됨
- 어떤 API 에서 리소스를 완전히 지우지 않고 임시 삭제 기능을 제공하거나 상태만을 바꾸는 기능을 제공하려면,
특별한 컨트롤러 리소스를 채택하고 클라이언트가 DELETE 메서드 대신POST 메서드를 사용해야 함
OPTIONS 메서드는 리소스의 사용 가능한 인터랙션을 기술한 메타데이터를 가져오는 데 사용해야 함
클라이언트는 OPTIONS 메서드를 사용하여 Allow 헤더에 포함된 리소스 메타 데이터를 가져옴
예를 들어 다음처럼 사용가능한 메서드를 가져옴 :
Allow : GET, PUT, DELETE응답 상태 코드
RFC 2616 Status-Line 문법
- Status-Line = HTTP-Version SP Status-Code SP Reason-Phrase CRLF
- HTTP/1.1 200 OK
범주 | 설명 |
1xx : 정보 | 전송 프로토콜 수준의 정보 교환 |
2xx : 성공 | 클라이언트 요청이 성공적으로 수행됨 |
3xx : 재전송 | 클라이언트는 요청을 완료하기 위해 추가적인 행동을 취해야 함 |
4xx : 클라이언트 오류 | 클라이언트의 잘못된 요청 |
5xx : 서버 오류 | 서버쪽 오류로 인한 상태 코드 |
규칙
200(”OK”)는 일반적인 요청 성공을 나타내는 데 사용
- REST API가 성공적으로 수행했음을 나타내는 코드
- 더 이상의 할당된 ‘2xx’ 계열의 응답코드가 없다는 뜻이기도 함
200(”OK”)는 응답 바디에 에러를 전송하는 데 사용해서는 안 된다
이 규칙을 사용하여 적절한 HTTP 응답 상태 코드를 사용해야 함. 부실한 HTTP 클라이언트에 부합하려는 그 어떤 타협도 해서는 안된다
201(”CREATED”)는 성공적으로 리소스를 생성 했을 때 사용해야 함
REST API는 클라이언트의 요청으로 새로운 리소스를 이용하여 컬렉션에 생성했거나 스토어에 추가했을 때 201 상태 코드로 응답함. 컨트롤러의 행동으로 새로운 리소스가 생겨났을 때도 201 상태 코드로 응답함
202(”Accepted”)는 비동기 처리가 성공적으로 시작 되었음을 알릴 때 사용해야 함
- 202 응답은 클라이언트의 요청이 비동기적으로 처리될 것임을 나타냄
- 이 응답 상태 코드는 유효한 요청이었지만, 최종적으로 처리되기까지는 문제가 생길 수도 있다는 것을 클라이언트에게 알려줌
- 보통 202 응답은 처리 시간이 오래 걸리는 액션에 사용됨
- 컨트롤러 리소스는 202 응답을 보낼 수 있지만 다른 리소스 타입은 보낼 수 없음
204(”No Content”)는 응답 바디에 의도적으로 아무것도 포함하지 않을 때 사용
- 보통 PUT, POST, DELETE 요청에 대한 응답으로 이용하는데, REST API가 응답 메시지의 바디에 어떠한 상태 메시지나 표현을 포함해서 보내지 않을 때 사용
301(”Moved Permanently”)는 리소스를 이동시켰을 때 사용
REST API 리소스 모델이 상당 부분 재설계되었거나 계속 사용할 새로운 URI를 클라이언트가 요청한 리소스에 할당하였다는 것을 나타냄. REST API는 응답의 Location 헤더에 새로운 URI를 기술해야 함
302(”Found”)는 사용하지 않는다
303(”See Other”)은 다른 URI를 참조하라고 알려줄 때 사용
- 303 응답은 처리가 끝난 컨트롤러 리소스가 잠재적으로 원하지 않는 응답 바디를 보내는 대신, 응답 리소스의 URI를 보냈음을 나타냄
- 303 상태 코드는 일반적으로 REST API가 클라이언트에 상태 다운로드를 강요하지 않으면서 참조 리소스를 보내는 것을 허용. 대신 클라이언트는 응답 Location 헤더에 있는 값으로 GET 요청을 보낼 수 있음
304(”Not Modified”)는 대역폭을 절약할 때 사용
리소스에 대한 상태정보가 있긴 하지만, 클라이언트에 이미 해당 상태의 최신 버전이 있다는 걸 의미할 때 사용(캐쉬!)
307(”Temporary Redirect”)는 클라이언트가 다른 URI로 요청을 다시 보내게 할 때 사용해야 한다
- HTTP/1.1은 최초의 302 상태 코드 의미를 반복하기 위해 307 응답 코드를 도입하였음
- 307 응답은 REST API가 클라이언트의 요청을 처리하지 않을 것임을 나타냄
- 클라이언트는 응답 메시지의 Location 헤더에 기술된 URI로 요청을 다시 보내야 한다.
- REST API는 요청된 클라이언트의 리소스에 임시 URI를 할당하여 상태 코드를 사용할 수 있음(예를 들어 307 응답은 클라이언트 요청을 다른 호스트로 바꾸는 데 사용)
400(”Bad Request”)는 일반적인 요청 실패에 사용해야 한다
다른 적절한 ‘4xx’ 오류 값이 없을 때 사용하는 일반적인 클라이언트의 에러 상태
4xx 범주의 오류는 클라이언트의 오류를 기술하는 도큐먼트를 응답 바디에 포함할 수 있다(요청 메서드가 HEAD일 경우는 제외)
401(”Unauthorized”)는 클라이언트 인증에 문제가 있을 때 사용해야 함
401 오류 응답은 클라이언트가 적절한 인증 없이 보호된 리소스를 사용하려 할 때 발생
403(”Forbidden”) 은 인증상태에 상관없이 액세스를 금지할 때 사용해야 한다
REST API에서 애플리케이션 수준의 접근 권한을 적용하고자 할 때 403을 사용
404(”Not Found”)는 요청 URI에 해당하는 리소스가 없을 때 사용해야 한다
404 오류 상태 코드는 말그대로 클라이언트가 요청한 URI에 해당하는 리소스가 존재하지 않을 때 사용함
405(”Method Not Allowed”)는 HTTP 메서드가 지원되지 않을 때 사용해야 한다
클라이언트가 허용되지 않은 HTTP 메서드를 사용하려 할 때, API는 405 오류 응답을 함
405 응답에는 Allow 헤더가 포함되어야 함. 예)
Allow : GET, POST406(”Not Acceptable”)은 요청된 리소스 미디어 타입을 제공하지 못할 때 사용해야 한다
클라이언트의 Accept 요청 헤더에 있는 미디어 타입 중 해당하는 것을 만들지 못할 때 발생함
예로, API가 application/json 데이터 포맷만 지원한다면, application/xml 포맷 데이터를 요청한 클라이언트는 406 응답을 받음
409(”Conflict”)는 리소스 상태에 위반되는 행위를 했을 때 사용해야 한다
클라이언트 요청에 의해 REST API 리소스가 불가능 또는 모순 상태가 될 수 있는 경우에 사용
예를 들어, 클라이언트가 비어 있지 않은 스토어 리소스를 삭제하라고 요청하면, REST API에서 이 응답 오류를 보냄
412(”Precondition Failed”)는 조건부 연산을 지원할 때 사용한다
- 412 오류 응답은 특정한 조건이 만족될 때만 요청이 수행되도록 REST API로 알려준다.
- 클라이언트가 요청 헤더에 하나 이상의 전제 조건을 지정할 경우 발생하며, 이러한 조건이 만족되지 않으면 412 응답은 요청을 수행하는 대신, 이 상태 코드를 보냄
- 4장에서 설명할 스토어는 조건부 PUT 요청을 지원해야 한다 에서 412 상태코드 사용 예시 있음
415(”Unsupported Media Type”)은 요청의 페이로드에 미디어 타입이 처리되지 못했을 때 사용해야 한다
415 오류 응답은 요청 헤더의 Content-Type에 기술한 클라이언트가 제공한 미디어 타입을 처리하지 못할 때 발생함. 예로, API가
application/json으로 포맷된 데이터만 처리할 수 있을 때, 클라이언트가 application/xml 로 포맷된 데이터로 요청하면 415 응답을 받음500(”Internal Server Error”)는 API가 잘못 작동할 때 사용해야 함
500은 일반적인 REST API 오류 응답이다.
웹 프레임워크는 대부분 예외 사항을 발생시키는 요청 핸들러 코드가 실행될 경우 자동적으로 이 응답 코드를 발생시킨다