RESTful API 설계: 리소스 구조화와 HTTP 메서드 활용

아래 내용은 MS RESTFul 웹 API 디자인 모범사례 문서를 참고한 내용입니다.

---

RESTFul API

• 리소스마다 해당 리소스를 고유하게 식별하는 URI인 식별자가 존재합니다.

    https://adventure-works.com/orders/1

• 가능하다면 리소스 URI는 동사(리소스에 대한 작업)가 아닌 명사(리소스)를 써야 합니다.

    https://adventure-works.com/orders // Good
    https://adventure-works.com/create-order // Avoid

• 리소스가 단일 실제 데이터 항목을 기반일 필요는 없습니다.
• 단순히 데이터베이스의 내부 구조를 반영하는 API는 좋지 않습니다.
  • REST의 목적은 엔터티 및 해당 엔터티에서 애플리케이션이 수행할 수 있는 작업을 모델링 하는 것입니다. 따라서 단순히 내부 구조를 반영하여 클라이언트가 내부 구현에 노출되어서는 안됩니다.
• 컬렉션 및 항목에 대한 URI를 계층 구조로 구성하는 것이 좋습니다.

/customers/{id}

• 리소스 URI를 컬렉션/항목/컬렉션보다 더 복잡하게 요구하지 않는 것이 좋습니다.

---

HTTP 메서드 측면에서 API 작업 정의

• GET
  • 지정된 URI에서 리소스의 표현을 검색
  • 응답 메시지의 본문은 요청된 리소스의 세부 정보를 포함
• POST
  • 지정된 URI에 새 리소스 생성
  • 요청 메시지 본문은 새 리소스의 세부 정보 제공
• PUT
  • 지정된 URI에 리소스를 만들거나 대체
  • 요청 메시지 본문은 만들거나 업데이트 할 리소스 지정
  • 동일한 PUT요청을 여러 번 해도 동일한 결과(idempotnent)이여야 함
• PATCH
  • 리존 리소스에 부분 업데이트 수행
  • 변경 내용만 보내기 때문에 PUT보다 더 효율적일 수 있음
• DELETE
  • 지정된 URI의 리소스 제거

리소스	POST	GET	PUT	DELETE
/customers	새 고객 만들기	모든 고객 검색	고객 대량 업데이트	모든 고객 제거
/customers/1	Error	고객 1에 대한 세부 정보 검색	고객 1이 있는 경우 고객 1의 세부 정보 업데이트	고객 1 제거
/customers/1/orders	고객 1에 대한 새 주문 만들기	고객 1에 대한 모든 주문 검색	고객 1의 주문 대량 업데이트	고객 1의 모든 주문 제거

---

HTTP 의미 체계 준수

미디어 유형

• HTTP 프로토콜에서 형식은 MIME 유형이라고 하는 미디어 유형을 사용하여 지정됩니다.
• JSON, XML
• 요청 또는 응답의 Content-Type 헤더는 표현 형식을 지정합니다.
• 예

POST 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 상태코드 415(지원되지 않는 미디어 유형)을 반환합니다.
• 클라이언트 요청엔 서버 응답메시지로부터 받는 미디어 유형 목록을 포함하는 Accept헤더가 포함될 수 있습니다.
  • 서버가 나열된 미디어 유형 중 어떤 것도 일치시킬 수 없는 경우 HTTP 상태코드 406(허용되지 않음)을 반환합니다.

GET

• 성공 : HTTP 상태코드 200
• 실패 : 리소스를 찾을 수 없는 경우 HTTP 상태코드 404(찾을 수 없음)
• 요청이 처리되었지만 HTTP 응답에 포함된 응답 본문이 없는 경우 HTTP 상태코드 204(콘텐츠 없음) 반환
  • 일치 항목이 없는 검색 작업 경우 해당

POST

• 새 리소스 만드는 경우 : HTTP 상태코드 201
  • 새 리소스를 만들지 않는 경우엔 HTTP 상태코드 200 반환
  • 작업의 결과를 응답 본문에 포함 할 수 있음
  • 반환 결과가 없으면 응답 본문 없이 HTTP 상태코드 204 반환
• 클라이언트가 잘못된 요청 : HTTP 상태코드 400(잘못된 요청) 반환

PUT

• 새 리소스를 만드는 경우 : HTTP 상태코드 201
  • 기존 리소스를 업데이트 할 경우 : HTTP 상태코드 200 or 204 반환
  • 기존 리소스를 업데이트 할 수 없는 경우 : HTTP 상태코드 409(충돌) 반환

DELETE

• 삭제 성공 : HTTP 상태코드 204(콘텐츠 없음) 응답
• 리소스가 없는 경우 : HTTP 상태코드 404(찾을 수 없음) 응답

---

비동기 작업

때로 POST, PUT, PATCH, DELETE 작업을 완료하는데 시간이 걸릴 수 있습니다. 이런 경우 요청 처리가 수락되었지만 아직 완료되지 않았음을 나타내는 HTTP 상태코드 202(수락됨)을 반환해야합니다.

---

메시지 본문의 빈 집합

성공적인 응답의 본문이 비어 있을 때마다 상태코드는 200이 아닌 204(콘텐츠 없음) 이어야 합니다. 검색 조건에 따른 응답이 빈 경우에도 마찬가지입니다.

---

데이터 필터링 및 페이지 매기기

/orders?minCost=n

위와 같이 API가 쿼리 문자열에 필터 조건을 전달하면 서버쪽에서 필터링된 결과를 반환할 수 있습니다. 만약, GET 요청이 다수의 항목을 반환할 경우 반환 데이터의 양을 제한하도록 Web API를 디자일 할 수 있습니다. 다음은 검색할 최대 항목 수와 시작 오프셋을 지정하는 쿼리 문자열입니다.

/orders?limit=25&offset=50

필드이름을 아래와 같이 정렬 매개 변수를 제공하여 데이터를 가져올 때 데이터를 정렬하는 전략을 사용할 수도 있습니다.

/orders?sort=ProductID