TIL > REST API

REST API :

  자원(Resource)을 HTTP URI로 표현하고, HTTP 프로토콜을 통해 요청과 응답을 정의하는 방식

 

구글에서 지향하는 API Method 방법 중에 익숙치 않았던 부분에 대해서 정리하였습니다.

POST :  

   생성된 자원에 대한 Location response header 를 응답 헤더에 추가하여 자원에 대한 정보를 얻을 수 있도록 하는 것을 권장한다.

POST http://api.contoso.com/account1/servers

응답 헤더
201 Created
Location: http://api.contoso.com/account1/servers/server321

PATCH :

  UPSERT semantics 을 지향한다. 즉 없다면 생성하고 있다면 요청값에 대해 변경하는 것인데, PUT 과의 차이점이라면 PUT 은 통채로 바꾸는 것이지만 PATCH는 요청한 값에 대해서만 변경하는 것이다. (PUT 은 데이터를 변경할 때에 위험하다보니 PATCH를 우선순위로 놔야 된다는 의미같다.)

 

Nested collections and properties

아래와 같이 중첩된 컬렉션에 대해서 정보를 얻어오는 URL을 정의할 수도 있다.

GET https://api.contoso.com/v1.0/people/123/addresses

Result:
{
  "value": [
    { "street": "1st Avenue", "city": "Seattle" },
    { "street": "124th Ave NE", "city": "Redmond" }
  ]
}

Filtering

아래와 같은 URL 형식으로 필터링 형식을 설정한다.

관련 가이드

# price 가 10 보다 작은 놈만 가져온다.
GET https://api.contoso.com/v1.0/products?$filter=price lt 10.00

# name이 'Milk' 이고 price 가 2.55 이하인 것만 가져온다.
GET https://api.contoso.com/v1.0/products?$filter=name eq 'Milk' or price lt 2.55

Sorting

아래와 같은 URL 형식으로 표출 순서를 설정한다. 

# name이 내림차순으로, hireDate는 오름차순으로 (defalut가 오름차순임)
GET https://api.contoso.com/v1.0/people?$orderBy=name desc,hireDate

 

ref:

https://github.com/Microsoft/api-guidelines/blob/master/Guidelines.md#741-post

 

좋은 REST API를 디자인 하는 방법

로이 필딩이 논문에서 제시한 REST 방법론을 보다 더 실용적으로 적용하기 위해 레오나르드 리차드슨은 REST API를 잘 적용하기 위한 4단계 모델을 만들었다.

2단계까지만 적용해도 좋은 API 디자인이라고 볼 수 있고, 이런 경우 HTTP API 라고도 부른다.

REST 성숙도 모델 - 0단계

HTTP 프로토콜을 사용하기만 해도 0단계이다.

다음과 같은 예시: 

REST 성숙도 모델 - 1단계

리소스가 무엇인지에 따라 각기 다른 엔드포인트로 구분하여 적용한다. 

또한 요청 실패 시, 응답으로 실패 사유를 같이 전달해야한다.

 

 

REST 성숙도 모델 - 2단계

앞서 0단계와 1단계 예시에서 보았듯, 모든 요청을 CRUD에 상관없이 POST로 하고 있다. 조회(READ)하기 위해서는 GET 메소드를 사용하여 요청을 보내고, 이때 GET 메소드는 body를 가지지 않기 때문에 query parameter를 사용하여 필요한 리소스를 전달해야한다.

API를 작성할 때, REST 성숙도 모델의 2단계까지 적용을 하면 대체적으로 잘 작성된 API라고 여긴다. 물론 로이 필딩은 앞서 이야기한 바와 같이 3단계까지 만족하지 못한다면 REST API가 아니기 때문에 HTTP API라고 불러야 한다고 주장하지만, 뒤에 만나게 되는 레퍼런스의 모범적인 API 디자인조차도 REST 성숙도 모델의 3단계까지 적용한 경우는 극히 드뭅니다. 따라서 3단계까지 무조건적으로 모두 적용해야 한다는 것은 아니다.

 

REST 성숙도 모델 - 3단계

3단계의 요청은 2단계와 동일하지만, 응답에는 리소스의 URI를 포함한 링크 요소를 삽입하여 작성한다는 것이 다르다.

응답에 들어가게 되는 링크 요소는 응답을 받은 다음에 할 수 있는 다양한 액션들을 위해 많은 하이퍼미디어 컨트롤을 포함하고 있다.