웹 API 디자인(RESTful API)

RESTful API

0. 들어가면서

아래의 공식문서를 짧게 정리했다.

docs.microsoft.com/ko-kr/azure/architecture/best-practices/api-design

API 디자인 지침 - Best practices for cloud applications

 

잘 디자인된 웹 API

 플랫폼이 독립적이어야 한다. 모든 사용자는 내부 API 방법과 상관없이 API를 호출할 수 있어야한다. 그러기 위해서는 표준 프로토콜을 사용해야한다. 그리고 웹 API는 사용자 애플리케이션과 독립적으로 기능을 업그래이드하고 추가가능해야한다.

 

1. REST(Representational State Transfer) 소개

 REST란 하이퍼 미디어 기반 분산 시스템을 구축하기 위한 아키텍처이다. 대부분의 REST 구현에서 애플리케이션 프로토콜로 HTTP를 사용하고, 이 지침에서는 HTTP를 위한 REST API 디자인에 중점을 둔다. 아제 HTTP를 사용하는 REST API의 디자인 원칙은 아래와 같다.

 

 

REST API는 리소스를 중심으로 디자인된다.

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

 즉, 위와 같은 url을 보면 고객 주문의 urI이라는 것을 알 수 있어야한다.

 

 

많은 Web API가 교환 형식으로 JSON을 사용한다. 위의 URI에 대한 GET요청의 응답(response)는 아래의 JSON이라고 할 수 있다.

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

 

 

일반적으로 REST API의 경우느 리소스에 표준 HTTP 동사를 사용하며, 그 예로는 GET, POST, PUT, PATHCH, DELETE라고 할 수 있다.

 

REST API는 하이퍼미디어 링크에 따라 구동되며 아래의 JSON 예는 주문과 관련된 고객을 가져오거나 업데이트를 하는 링크라는 것을 알 수 있다.

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

 

 

1.1  Wep API의 RESTful 정도

• 수준 0 : 한 URI를 정의한다. 모든 작업은 이 URI에 대한 POST 요청이다.
• 수준 1 : 개별 리소스에 대한 별도의 URI를 만든다
• 수준 2 : HTTP 메서드를 사용하여 리소스에 대한 작업을 정희한다.
• 수준 3 : 하이퍼미디어(HATEOAS)를 사용한다.

대부분의 여러 Web API가 수준 2 정도에 해당하고 수준 3이 Fielding의 정의에 따르면 진정한 RESTful에 해당한다.

 

 

2. 리소스 중심의 API

웹 API는 비즈니스 entity(엔터티)에 집중해야한다.

예를 들염 전자 상거래 시스템에서는 기본 엔터티가 고객과 주문이다. 이때 HTTP POST 요청으로 주문을 할 수 있다. HTTP 응답으로는 주문이 성공적으로 수행됐는지 여부가 나타난다. 이때 리소스 동사가 아닌 명사(리소스)를 기반으로 해야한다. 복수 명사도 가용 가능하다.

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

 핵심은 데이터베이스의 내부 구조를 반영하는 API는 만들면 안되고, REST의 목적인 entity나 애플리케이션이 수행하는 작업을 모델링하는 것이다. 아래의 예를 보자.

 

/customers     고객의 선택한 목록임을 짐작할 수 있다.

/customers/5   ID가 5인 고객의 경로임을 알 수 있다.

/customers/{id}  이런식으로 웹 API를 직관적으로 유지해야한다.

 

/customers/5/orders        ID가 5인 고객에 대한 모든 주문을 나타낼 수 있다.

 

/orders/99/customer        99번 재품을 구매한 고객. 그러나 이런식으로 URI를 추가해도 되지만, 너무 많이 확장하면 구현이 어려울 수도 있다.

 

 

/customers/1/orders/99/products         이런 식으로 적으면 유연성이 떨어진다. 아래와 같이 바꾸자.

=> /customers/1/1orders 로 고객1의 모든 주문을 찾고 /orders/99/products로 이 주문의 제품을 찾는 방식으로 가는게 더 좋다. 즉, 복잡하면 안된다.

 

 

 

 

3. HTTP 메서드를 기준으로 정리

 아래의 표를 보고 먼저 이해를 해보고 설명을 읽자.

3.1 GET 메서드

 지정된 URI에서 리소스의 표현을 검색한다. 성공적인 GET 메서드는 일반적으로 HTTP 상태 코드 200(정상)을 반환 한다. 리소스를 못찾으면 404(찾을 수 없음)을 반환해야한다.

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

 

3.2 POST 메서드

 지정된 URI에 새 리소스를 만든다. 새 리소스를 만드는 경우 HTTP 상태 코드 201(만들어짐)을 반환한다. 새 리소스를 만들지 않고 일부 처리만 수행하면 200을 반환하고 반환할 결과가 없으면 204(내용 없음)을 반환한다. 만약 클라이언트가 잘못된 데이터를 요청하면 400(잘못된 요청)을 반환해야한다.

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}

 

3.3 PUT 메서드

 지정된 RUI에 리소스를 만들거나 대체한다. 업데이트할 리소스를 지정한다

 

 

3.4 PATCH 매서드

 리소스의 부분을 업데이트 한다.

 

 

3.5 DELETE 매서드

 URI의 리소스를 제거한다.