[REST 설계] HTTP 메소드와 응답코드

HTTP 의 요청 메서드와 응답 상태 코드

---

 

이전 글 : URI 식별자 설계

2022.05.21 - [Engineering/SW Design] - [REST 설계] URI 식별자 설계

[REST 설계] URI 식별자 설계

 

 

요청 메서드

클라이언트는 서버와 인터랙션 하는 메서드를 HTTP 요청 메시지의 Request-Line 부분에 명시한다.

REST API리소스 모델에서 각 HTTP 메서드는 잘 정의된 고유한 의미가 있고, REST API의 요청 메서드는 HTTP/1.1 부터 이어져온 포맷의 모든 측면을 수용한다.

• GET
  • 리소스 상태의 표현 즉, 값을 얻을 때 사용한다.
• HEAD
  • 리소스 상태에 대한 메타데이터를 얻을 때 사용한다.
• PUT
  • 새로운 리소스를 스토어에 추가하거나 기존 리소스를 갱신 할때 사용한다.
• DELETE
  • 부모에서 리소스를 제거한다.
• POST
  • 컬렉션에 새로운 리소스를 만들어 내거나 컨트롤러를 실행 할 때 사용한다.

규칙1) GET 메서드나 POST 메서드를 사용하여 다른 요청 메서드를 처리해서는 안된다.

한정된 HTTP문법으로 클라이언트에 대응하기 위해서 HTTP 요청 메서드를 원래의 의미와 다르게 사용하는 REST API를 설계 해서는 안된다.

 

규칙2) GET 메서드는 리소스의 상태 표현을 얻는데 사용해야 한다.

클라이언트는 특정한 형식의 GET 메서드를 요청 메시지에 추가하여 리소스의 상태 정보를 요청한다.

클라이언트의 GET 요청 메시지는 바디 없이 헤더로만 구성된다.

웹서비스는 구조상 GET 메서드의 특성에 많이 의존하며, 클라이언트에서 GET 요청을 반복해도 문제가 없어야 하며 캐시는 리소스를 제공하는 원래 서버와 통신하지 않고도 캐시된 내용을 제공 할 수 있어야 한다.

 

규칙3) 응답 헤더를 가져올 때는 반드시 HEAD 메서드를 사용해야 한다.

클라이언트는 HEAD 메서드를 사용하여 헤더 정보만 가져온다.

즉 HEAD 는 GET과 동일한 응답을 주지만 데이터가 들어있는 바디 영역이 없다고 보면 된다.

따라서 클라이언트는 HEAD 메서드를 사용하여 리소스 존재 여부를 확인 하거나 메타데이터만 읽을 수 있다.

 

규칙4) PUT 메서드는 리소스를 삽입하거나 저장 된 리소스를 갱신하는 데 사용해야 한다.

PUT 메서드는 클라이언트가 기술한 URI로 스토어에 새로운 리소스를 추가하는데 사용한다.

이미 스토어에 저장 된 리소스를 갱신하거나 다른 것으로 대체하는데 에도 PUT 메서드를 사용한다.

• PUT /accounts/skidrow6122/buckets/objects/4321

뭔가 데이터가 담겨서 요청 되어야 서버는 리소스를 추가하던 갱신하던 액션을 취할 것이므로 당연히 PUT 요청 메시지에는 클라이언트에서 저장하려는 리소스를 표현하는 부분이 포함되어야 한다.

 

규칙5) PUT 메서드는 변경 가능한 리소스를 갱신하는 데 사용해야 한다.

클라이언트는 PUT 요청 메서드를 사용해서 리소스를 변경한다.

PUT 요청 메시지에는 원하는 형태로 변경하고픈 메시지 바디를 포함할 수 있다.

 

규칙6) POST 메서드는 컬렉션에 새로운 리소스를 만드는데 사용해야 한다. (POST 의 첫번째 유스케이스)

클라이언트는 POST 메서드를 사용해서 컬렉션 안에 새로운 리소스를 만든다.

POST 요청 바디는 새로운 리소스를 생성하기 위한 데이터를 포함 하는데,이것은 곧 서버의 컬렉션에 추가 된다.

• POST /leagues/lotte/teams/players

본 예시는 게시판에 새로운 메시지를 등록 하는 것과 비슷하다.

 

규칙7) POST 메서드는 컨트롤러를 실행 하는데 사용해야 한다. (POST 의 두번째 유스케이스)

클라이언트는 POST 메서드를 사용해서 기능을 돌릴 수 있는 컨트롤러 리소스를 동작 시킨다.

POST 요청 메시디는 컨트롤러 리소스 기능의 입력값을 헤더나 바디에 포함 시킨다.

POST 메서드는 리소스를 가지고 오거나, 저장하거나, 지우는데 사용하지 않는다.

POST 메서드는 사용 할 때마다 리소스의 상태 값이 계속 바뀔 수 있어 그리 안전하지 않으며, 결과를 예측할 수 도없고 부작용 없이 반복적으로 사용하는 것을 보장할 수 도 없다는 의미이다.

• POST / alerts/2324/resend

 

규칙8) DELETE 메서드는 그 부모에서 리소스를 삭제 하는데 사용한다.

주어진 리소스에 DELETE 요청이 수행되면 클라이언트는 더이상 그 리소스를 볼 수 없다.

• DELETE /accounts/skidrow6122/buckets/objects/4321

아까 PUT 한 리소스를 삭제 하는 사용 예시이다.

DELETE 메소드는 일단 한번 들어가면 리소스를 완전 삭제 하는 용도로 사용되므로 만약 API를 통해 어떤 리소스를 완전히 지우지 않은 임시삭제 또는 상태만 바꾸고자 하는 기능을 제공하기 위해서는, 컨트롤러 리소스를 구현하여 클라이언트가 DELETE 대신 POST 메서드를 사용하게 해야 한다.

 

규칙9) OPTIONS 메서드는 리소스의 사용 가능한 인터랙션을 기술한 메타데이터를 가져오는데 사용한다.

클라이언트는 OPTIONS 메서드를 사용하여 Allow 헤더에 포함 된 리소스 메타데이터를 가져온다.

• Allow: GET, PUT, DELETE

POST 와 PUT 의 용도가 조금 애매 할 수 있는데 간단히 정리하면,

1. POST는 리소스의 생성을 주로 담당하며, POST 는 요청 할때 마다 새로운 리소스가 생성된다. 또한 POST request 의 response 는 caching 가능 하다.

→ Request 에 포함된 body 를 요청 URI 리소스 하위 Entity 로 새롭게 Create 한다.

→ 따라서 Request URI는 리소스의 Entity를 나타내는 Collection URI 여야 한다.

→ 예를 들자면 선수들이 모인 /players 라는 Collection 하위에 새로운 선수(Entity)를 생성하는 것이다.

 

2. PUT은 리소스의 생성과 수정을 담당하는데, PUT은 요청 할때마다 같은 리소스를 반환하며 이는 값을 갱신 한다는 의미 이다. 또한 response 값은 caching 불가능 하다.

→ Request URI 에 있는 리소스가 존재 한다면? Request 에 포함된 body 값으로 리소스를 Update 한다.

→ 만약 Request URI 에 있는 리소스가 존재 하지 않다면? 리소스를 Create 한다.

→ 기존의 /players 라는 Collection URI에 더해서 /players/{playerId} 와 같이 해당 리소스의 식별자를 함께 나타내 줘야 한다.

 

POST 메서드와 PUT 메서드

 

 

응답 상태 코드

REST API는 HTTP 응답 메시지의 status line 부분을 사용하여 클라이언트가 요청한 결과를 알려준다.

HTTP는 40개의 표준상태 코드를 정의하여 클라이언트가 요청한 결과를 전달 하는데 사용하며 다섯가지 카테고리로 분류한다.

• 1xx : 전송 프로토콜 수준의 정보 교환
• 2xx : 성공 코드. 클라이언트의 요청이 성공적으로 수행 됨
• 3xx : 재전송. 클라이언트는 요청을 완료하기 위해 추가적인 행동을 취해야 함
• 4xx : 클라이언트 오류. 클라이언트의 잘못 된 요청
• 5xx : 서버 오류. 서버에서 오류가 일어난 리턴을 의미

규칙1) 200(”OK”) 는 일반적인 요청 성공을 나타내며, 응답 바디에 에러를 전송하는데 사용 하면 안된다.

204와는 달리 200응답은 응답 바디가 들어가 있고, 반드시 결과에 맞는 코드를 사용한다.

 

규칙2) 201(”Created”) 는 성공적으로 리소스를 생성 했을때 사용한다.

클라이언트의 요청으로 새로운 리소스를 이용하여 컬렉션에 생성 했거나 스토어에 추가했을때 201을 리턴한다.

 

규칙3) 202(”Accepted”) 는 비동기 처리가 성공적으로 시작되었음을 알릴 때 사용한다.

202는 클라이언트의 요청이 비동기적으로 처리될 것임을 알린다. 즉, 요청 자체는 유효한것이 맞지만 최종 처리 까지는 문제가 생길 수도 있다는 것을 클라이언트에게 알려주며 주로 처리 시간이 오래 걸리는 액션에 사용한다.

 

규칙4) 204(”No content”) 는 응답 바디에 의도적으로 아무것도 포함하지 않을때 사용한다.

주로 PUT, POST, DELETE 요청에 의한 응답으로 이용하며, GET 에도 활용 될 수 있는데 이때는 요청된 리소스는 존재 하나 바디에 포함시킬 어떤 값도 없을때 를 나타낸다.

 

규칙5) 301(”Moved Permanently”) 는 리소스를 이동시켰을 때 사용한다.

REST API 리소스 모델이 상당 부분 재설계 되었거나 계속 사용 할 새로운 URI를 클라이언트가 요청한 리소스에 할당 하였다는 것을 나타낸다. 응답 헤더에는 새로운 URI가 기술 된다.

 

규칙6) 400(”Bad Request”) 는 일반적인 요청 실패에 사용한다.

 

규칙7) 401(”Unauthorized”) 는 클라이언트 인증 문제가 있을때 사용한다.

클라이언트가 적절한 인증 없이 보호된 리소스를 사용하려고 할때 발생한다.

 

규칙8) 403(”Forbidden”) 은 인증 상태에 관계없이 액세스를 금지할 때 사용한다.

클라이언트 요청과 인증 상태는 정상이지만, REST API가 요청에 응하지 않는 경우를 의미한다.

즉, REST API에서 어플리케이션 수준의 접근권한을 적용하고자 할때 403을 쓰며, 클라이언트에게 허용된 범위 외의 리소스에 접근 하고자 할때 이 코드를 리턴한다.

 

규칙9) 404(”Not Found”)는 요청 URI에 해당하는 리소스가 없을때 사용한다.

 

규칙10) 406(”Not Acceptable”)은 요청된 리소스 미디어 타입을 제공하지 못할 때 사용한다.

클라이언트의 Accept 요청 헤더에 있는 미디어 타입 중 해당하는 것을 만들지 못할때 발생한다. 예를들어 API가 json 포맷만 지원한다면 xml을 요청한 클라이언트에게 406을 리턴해야 한다.

 

규칙11) 500(”Internal Server Error”) 은 API가 잘 못 작동할때 사용한다.

개발 중 테스트 시 가장 많이 보게 되는 응답으로 그냥 서버단에서 뭔가 잘못되었다는 뜻이다.

 

 

 

---

REST API 인터랙션 시 사용되는 HTTP 메서드의 종류 별 쓰임새와 표준 응답 코드에 대해 정리 해보았다.

다음 글에서는 HTTP 헤더와 미디어 타입을 통해 전달되는 REST API의 메타데이터에 대한 디자인 규칙을 다룬다.