REST API

잘 디자인된 API의 경우 플랫폼에 독립되어야 하고 확장성을 지녀야한다.

REST API

REST(Representational State Transfer)는 어떤 기본 프로토콜과도 독립적이며 HTTP에 연결될 필요가 없다.
하지만 일반적인 REST API는 프로토콜로 HTTP를 사용한다.

RESTful API 디자인 원칙

• REST API는 리소스를 중심으로 디자인된다.
  또한 클라이언트에 엑세스 할 수 있는 모든 종류의 개체, 데이터 또는 서비스가 리소스에 포함된다.

• 리소스마다 해당 리소스를 고유하게 식별하는 URI인 식별자가 있다.
  예를 들어 HTTP기반의 특정 고객 주문의 URI는 다음과 같다.

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

• 클라이언트와 서버가 리소스의 표현을 교환한다.
  주로 JSON 형식을 교환한다. 위의 URI에 대한 GET 요청은 이러한 데이터를 반환한다.

{ "orderId": 1, "orderValue": 99.9, "productId": 1, "quantity": 1 }

• 리소스에 표준 HTTP 메서드를 통해 작업을 지시한다.
  대표적으로 GET,POST,PUT,PATCH,DELETE등이 있다.

• Stateless이다. HTTP 요청은 독립적이고 임의순서로 발생하기 때문이다.
  서버는 정보를 리소스에만 저장되고 요청이 들어오면 해당하는 데이터를 반환하면 되기때문에 확장성이 우수하다.

• 하이퍼미디어 링크에 따라 구동된다.
  고객 정보를 가져오거나(GET), 업데이트(PUT) 하는 링크를 포함한다.

{
  "orderID": 3,
  "productID": 2,
  "quantity": 4,
  "orderValue": 16.6,
  "links": [
    {
      "rel": "product",
      "href": "https://adventure-works.com/customers/3",
      "action": "GET"
    },
    {
      "rel": "product",
      "href": "https://adventure-works.com/customers/3",
      "action": "PUT"
    }
  ]
}

REST API 디자인

• REST API는 리소스를 구성으로 디자인해야 한다.
  즉 리소스 URI는 동사(작업)이 아닌 명사(리소스)를 기반으로 해야한다

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

• REST API의 엔티티는 컬렉션(주문, 고객)등으로 그룹화된다.
  컬렉션은 별도의 리소스이며 고유한 URI가 있어야한다.
  다음은 주문 컬렉션의 URI이다.

  https://adventure-works.com/orders

• 컬렉션 하위 요소들에 URI에 일관적인 명명 규칙을 적용하여 관리한다.
  다음은 주문번호가 5인 주문이다.
  즉 orders/{id}와 같은 형식으로 관리한다.

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

HTTP 메서드를 기준으로 API 작업 정의

GET

URI에서 리소스의 표현을 검색한다.
리소스의 세부정보를 응답메시지의 본문에 담는다.

POST

URI에 새 리소스를 만든다.
요청 메시지의 본문에 담긴 리소스를 새로 만든다.
실제로 리소스를 만들지 않는 작업을 수행하기도 한다(로그인 등)

PUT

URI에 리소스를 만들거나 대체한다.
요청 메시지의 본문에 만들 또는 업데이트할 리소스를 담는다.

PATCH

리소스를 수정(부분 업데이트)한다.
요청 메시지의 본문에 리소스에 적용할 변경 내용을 담는다.

DELETE

URI의 리소스를 제거합니다.

HTTP 의미 체계 준수

HTTP 사양을 준수하기 위한 고려사항이 몇 가지 있다.

미디어 유형

리소스 표현의 형식을 요청 또는 응답의 Content-Type 헤더를 통해 지정한다.
미디어 유형을 지원하지 않을 경우 415(지원되지 않는 미디어) 에러를 반환한다.

Content-Type:application/json; charset=utf-8

클라이언트 요청에는 Accept 헤더를 통해 서버에서 받는 미디어 유형을 지정할 수 있다.

서버에서 해당 미디어 유형을 일치시킬 수 없을경우 406(허용되지 않음)을 반환한다.

GET

성공할 경우 200(정상)찾을 수 없을 경우 400(찾을 수 없음)을 반환한다.

POST

새 리소스를 만드는 경우 201(만들어짐)을 반환한다.
새 리소스를 만들지 않는 경우 200을 반환한다.
반환할 경과가 없는 경우 204(내용 없음)을 반환한다.
새 리소스의 URI는 응답의 Location헤더에 포함된다.

PUT

PUT은 POST와 같은 HTTP 상태코드를 반환한다.
하지만 기존 리소스를 업데이트 할 수 없는 경우 409(충돌)을 반환한다.

PATCH

JSON 패치 혹은 JSON 병합 패치가 있다.

지원되지 않는 패치 형식일경우 415를 반환한다.
패치 문서의 형식이 잘못되었을 경우 400을 반환한다.
패치문서가 유효하지만 리소스에 적용할 수 없을 경우 409를 반환한다.

JSN 병합 패치

변경 또는 추가할 필드의 하위집합만 포함한다.
혹은 null값을 지정하여 필드를 삭제할 수 있다.( 원래 null값을 지닌다면 적합하지 않다.)

미디어 유형은 application/merge-path+json이다.

JSON 패치

명식적으로 null값을 포함할 수 있는 경우 JSON패치가 적절하다.
작업에는 추가, 제거, 바꾸기, 복사 및 텍스트(유효성검사)가 포함된다.

미디어 유형은 application/json-patch+json이다.

DELETE

삭제에 성공하면 204(콘텐츠 없음)을 반환하고 응답 본문에는 정보를 포함하지 않는다.
리소스가 없는경우 404를 반환한다.

데이터 필터링

데이터 필터링의 경우 쿼리 스트링을 이용하여 처리한다.
다음 URI는 최대 항목수와 컬렉션의 시작 오프셋을 지정하는 쿼리 스트링이다.

/orders?limit=25&offset=50

ref

(Web API디자인)[https://docs.microsoft.com/ko-kr/azure/architecture/best-practices/api-design]