HTTP 의미 체계 준수

HTTP 의미 체계 준수

• HTTP 사양을 준수하는 API 디자인에 대한 일반 고려 사항을 알아보자

 

미디어 유형

• 클라이언트와 서버는 Resource Representation을 교환함
  • POST 요청의 경우 요청 본문에 생성할 Resource의 Representation이 포함됨
  • GET 요청의 경우 응답 본문에 가져온 Resource의 표현이 포함됨

 

HTTP 프로토콜에서의 표현 형식

• HTTP 프로토콜에서 형식은 MIME 유형이라고 하는 _미디어 유형_을 사용하여 지정됨
• 이진이 아닌 데이터의 경우 대부분의 Web API는 JSON과 XML을 지원함
  • JSON 미디어 유형: application/json
  • XML 미디어 유형: application/xml

 

미디어 유형 지정

• 요청 / 응답의 Content-Type 헤더는 표현 형식을 지정함
  • JSON 데이터를 포함하는 POST 요청의 예시

  POST [https://adventure-works.com/orders](https://adventure-works.com/orders) HTTP/1.1  
  Content-Type: application/json; charset=utf-8  
  Content-Length: 57  
  
  { "id":1, "Name": "Gizmo", "Category":"Widgets", "Price":1.99 }  

 

미디어 유형과 관련한 서버 응답

• 서버에서 미디어 유형을 지원하지 않는 경우
  • HTTP status code: 415(지원되지 않는 미디어 유형)
• 클라이언트 요청에는 클라이언트가 응답 메세지에서 서버로부터 받는 미디어 유형 목록을 포함하는Accept 헤더가 포함될 수 있음

GET [https://adventure-works.com/orders/2](https://adventure-works.com/orders/2) HTTP/1.1  
Accept: application/json  

• 서버가 나열된 미디어 유형 중 어떤 것도 일치시킬 수 없는 경우
  • HTTP status code: 406(혀용되지 않음)

 

 

GET 메서드

코드	상태 메세지	의미
200	Sucess	정상
204		콘텐츠 없음. 요청이 처리되었지만 HTTP 응답에 포함된 응답 본문이 없는 경우
404	Not Found	리소스를 찾을 수 없음

 

POST 메서드

코드	상태 메세지	의미
201	만들어짐	새 Resource의 URI는 응답 Location 헤더에 포함됨 응답 본문은 Resource의 Representation을 포함함
200		메서드가 요청의 일부를 처리하지만 새로운 Resource를 생성하지 않는 경우 작업의 결과를 응답 본문에 포함
204	내용없음	반환할 경과가 없는 경우 응답 본문 없이 반환
400	잘못된 요청	클라이언트가 잘못된 데이터를 요청에 배치한 경우 응답 본문에는 오류에 대한 추가 정보 또는 자세한 정보를 제공하는 URI 링크 포함 가능

 

PUT

• 컬렉션의 복수 Resource에 대한 업데이트를 일괄 처리할 수 있는 일괄 HTTP PUT 작업 구현을 가정해보자
  • PUT 요청은 컬렉션의 URI를 지정해야 함
  • 요청 본문에 수정할 Resource의 세부 정보를 보내야 함
  • 데이터 전송량을 줄이고 성능 향상 가능

코드	상태 메세지	의미
201	만들어짐	새 Resource 생성
200	정상	기존 Resource를 업데이트 하는 경우
204	내용 없음	기존 Resource를 업데이트 하는 경우
409	충돌	기존 Resource를 업데이트 할 수 없는 경우

 

 

PATCH

• 클라이언트는 PATCH 요청 시 변경 내용을 _패치 문서_의 형태로 기존 리소스에 보냄
• 서버는 패치 문서를 처리하여 업데이트 수행
  • 패치문서는 Resource 전체가 아닌 적용할 변경 내용만 설명
• PATCH 메서드에 대한 사양에서 패치 문서에 대한 특정 형식을 정의하지 않고 있으므로 형식은 요청의 미디어 형식에서 유추해야 함
  • PATCH 메서드에 대한 사양: https://tools.ietf.org/html/rfc5789

 

 

PATCH 요청 처리 시 발생할 수 있는 오류 조건

코드	상태 메세지	오류 조건
400	잘못된 요청	패치 문서의 형식이 잘못된 경우
409	충돌	패치 문서가 유효하지만 현재 상테에서 변경 내용을 리소스에 적용할 수 없는 경우
415	지원되지 않는 미디어 형식	지원되지 않는 패치 문서 형식인 경우

 

 

JSON 기반 패치 형식

JSON 패치

• 미디어 유형: application/json-patch+json
• 작업의 결과로 적용할 변경 내용을 지정
  • 작업에는 추가, 제거, 바꾸기, 복사 및 테스트(값 유효성 검사)가 포함됨
• JSON 패치 세부정보: https://www.rfc-editor.org/rfc/rfc6902

 

JSON 병합 패치

• 미디어 유형: application/merge-patch+json
• 패치 문서는 원래 JSON Resource와 동일한 구조를 가짐
• 변경 또는 추가할 필드의 하위 집합만 포함
• 필드 값에 null 지정 시 필드 삭제 가능
  • 원본 Resource가 명시적 null 값을 가질 수 있는 경우, 패치문서에서 null이 가지는 특별한 의미 때문에 병합 패치는 적합하지 않음
• 패치 문서는 서버에서 업데이트를 적용할 순서를 지정하지 않음
  • 데이터 및 도메인에 따라 업데이트 순서가 중요할 수도, 중요하지 않을 수도 있으므로 주의
• JSON 병합 패치 세부정보: https://tools.ietf.org/html/rfc7396

 

예시

• 원본 Resource의 JSON 표현

{  
  "name": "gizmo",  
  "category": "widgets",  
  "color": "blue",  
  "price": 10  
}  

• 위의 원본 Resource에 가능한 JSON 병합 패치
  • price 업데이트, color 삭제, size 추가를 지시
  • name과 category는 수정되지 않음

{  
  "price": 12,  
  "color": null,  
  "size": "small"  
}  

 

 

DELETE

• 성공 시, 프로세스가 성공적으로 처리되었지만 응답 본문에 추가 정보가 없음을 나타내는 204(콘텐츠 없음) 으로 응답
• Resource가 없는 경우 404(Not Found)를 반환할 수도 있음

 

비동기 작업

• POST, PUT, PATCH 또는 DELETE 작업 완료 시 시간이 걸리는 처리가 필요할 수 있음
• 처리 작업 완료 시까지 기다렸다가 응답을 보내는 경우 허용되지 않는 수준의 대기 시간이 발생할 수도 있음
• 이러한 경우 비동기 작업을 수행하는 방안을 고려해봐야 함
• 장기 실행 요청에 대한 비동기 지원 제공: https://learn.microsoft.com/ko-kr/azure/architecture/best-practices/api-implementation#provide-asynchronous-support-for-long-running-requests
• 비동기 요청에 대한 회신 패턴: https://learn.microsoft.com/ko-kr/azure/architecture/patterns/async-request-reply

 

비동기 작업에서 요청의 status를 반환하는 엔드포인트를 표시하는 경우

• 요청 처리가 수락되었지만 아직 완료되지 않았음을 나타내는 202(수락됨) 을 반환
• 클라이언트가 status 엔드 포인트를 polling하여 status를 모니터 할 수 있도록 비동기 요청의 status를 반환하는 엔드포인트를 표시해야 함
• 202 응답의 Location 헤더에 status 엔드 포인트의 URI를 포함해야 함

HTTP/1.1 202 Accepted  
Location: /api/status/12345  

• 클라이언트가 해당 엔드 포인트에 GET 요청을 보내는 경우
  • 응답에는 요청의 현재 status가 포함되어야 함
  • 필요에 따라 예상 완료 시간 또는 작업 취소 링크를 포함할 수 있음

  HTTP/1.1 200 OK  
  Content-Type: application/json  
  
  {  
   "status": "In progress",  
   "link": { "rel":"cancel", "method":"delete", "href":"/api/status/12345" }  
  }  

 

비동기 작업에서 새 Resource를 생성하는 경우

• 작업 완료 후 status 엔드포인트에서 303(다른 항목 보기)를 반환해야 함
• 303 응답에 새로운 Resource의 URI를 제공하는 Location 헤더를 포함

HTTP/1.1 303 See Other  
Location: /api/orders/12345  

 

메세지 본문의 빈 집합

• 성공적인 응답의 본문이 비어 있는 경우: 204(콘텐츠 없음)
• 항목이 없는 필터링된 요청에 대한 응답과 같은 빈 집합: 204(콘텐츠 없음)