RESTful API architecture design

REST API

REST는 Representational State Transfer의 약자이며, 하이퍼미디어 기반 분산 시스템을 구축하기 위한 아키텍처 스타일을 뜻한다. API는 Application Programming Interface의 약자로 애플리케이션 소프트웨어를 구축하고 통합하는 정의 및 프로토콜 세트입니다.

RESTful API를 통해 요청이 수행될 때 RESTful API는 리소스 상태에 대한 표현을 요청자에게 전송하며 정보 또는 표현은 HTTP: JSON, HTML, XLT 또는 일반 텍스트를 통해 몇 가지 형식으로 전송되고 그 중에서도 JSON을 널리 사용됩니다.

RESTful API의 디자인 원칙

• 리소스를 중심으로 디자인되며, 클라이언트에서 액세스할 수 있는 모든 종류의 개체, 데이터 또는 서비스가 리소스에 포함
• 리소스마다 고유하게 식별하는 URI인 식별자가 존재
• 클라이언트가 리소스의 표현을 교환하여 서비스와 상호 작용, 많은 Web API가 교환 형식으로 JSON을 사용
• HTTP를 기반으로 하는 REST API의 경우 리소스에 표준 HTTP 동사 수행 작업을 사용하는 것이 균일한 인터페이스에 포함, 일반적인 작업으로 GET, POST, PUT, PATCH 그리고 DELETE
• 상태 비저장 요청 모델을 사용합니다. HTTP 요청은 독립적이어야 하고 임의 순서로 발생할 수 있으므로, 요청 사이에 일시적인 상태 정보를 유지할 수 없습니다. 정보는 리소스 자체에만 저장되며 각 요청은 자동 작업이어야 합니다.
• REST API는 표현에 포함된 하이퍼미디어 링크에 따라 구동

2008년에 Leonard Richardson은 Web API에 대한 다음과 같은 성숙도 모델을 제안

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

API 디자인 구성

리소스 URI는 동사(리소스에 대한 작업)가 아닌 명사(리소스)를 기반

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

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

단순히 데이터베이스의 내부 구조를 반영하는 API를 만들지 마세요. REST의 목적은 엔터티 및 해당 엔터티에서 애플리케이션이 수행할 수 있는 작업을 모델링하는 것, 클라이언트는 내부 구현에 노출되면 안 됩니다

컬렉션 및 항목에 대한 URI를 계층 구조로 구성하는 것이 좋습니다.

예를 들어 /customers는 고객 컬렉션의 경로이고, /customers/5는 ID가 5인 고객의 경로라면 매개 변수가 있는 URI 경로를 기반으로 요청을 라우팅할 수 있으므로 개발자는 경로 /customers/{id}에 대한 경로를 정의

/customers/1/orders/99/products과 같은 URI 수준의 복잡성은 유지하기 어려울 수 있으며 나중에 리소스 사이의 관계가 변하면 유연성이 떨어집니다

// 리소스 URI는 아래보다 복잡하지 않게 
// 컬렉션/항목/컬렉션

/customers/1/orders

HTTP 메서드 측면에서 API 작업

POST, PUT 및 PATCH의 차이점

POST 요청은 리소스를 만듭니다. 서버는 새 리소스에 대한 URI를 할당하고 클라이언트에 해당 URI를 반환

PUT 요청은 리소스를 만들거나 또는 기존 리소스를 업데이트합니다. 클라이언트는 리소스의 URI를 지정합니다. 요청 본문에는 리소스의 완전한 표현이 포함됩니다. 이 URI를 사용하는 리소스가 이미 있으면 리소스가 대체됩니다. 아직 없고 서버에서 리소스 만들기를 지원하는 경우 새 리소스가 생성됩니다. PUT 요청은 컬렉션보다는 특정 고객 같은 개별 항목인 리소스에 가장 자주 적용

PATCH 요청은 기존 리소스에 부분 업데이트를 수행합니다. 클라이언트는 리소스의 URI를 지정합니다. 요청 본문은 리소스에 적용할 변경 내용을 지정, HTTP 의미 체계 준수

GET 메서드

성공적인 GET 메서드는 일반적으로 HTTP 상태 코드 200(정상)를 반환합니다. 리소스를 찾을 수 없는 경우 메서드가 404(찾을 수 없음)를 반환해야 합니다.

요청이 처리되었지만 HTTP 응답에 포함된 respose 본문이 없는 경우 HTTP 상태 코드 204(콘텐츠 없음)를 반환해야 합니다

POST 메서드

POST 메서드는 새 리소스를 만드는 경우 HTTP 상태 코드 201(만들어짐)을 반환합니다. 새 리소스의 URI는 응답의 Location 헤더에 포함됩니다. 응답 본문은 리소스의 표현을 포함합니다.

이 메서드가 일부 처리를 수행하지만 새 리소스를 만들지 않는 경우 메서드는 HTTP 상태 코드 200을 반환하고 작업의 결과를 응답 본문에 포함할 수 있습니다. 또는 반환할 결과가 없으면 메서드가 응답 본문 없이 HTTP 상태 코드 204(내용 없음)를 반환할 수 있습니다.

클라이언트가 잘못된 데이터를 요청에 배치하면 서버에서 HTTP 상태 코드 400(잘못된 요청)을 반환해야 합니다. 응답 본문에는 오류에 대한 추가 정보 또는 자세한 정보를 제공하는 URI 링크가 포함될 수 있습니다.

PUT 메서드

PUT 메서드는 POST 메서드와 마찬가지로 새 리소스를 만드는 경우 HTTP 상태 코드 201(만들어짐)을 반환합니다. 이 메서드는 기존 리소스를 업데이트할 경우 200(정상) 또는 204(내용 없음)를 반환합니다. 상황에 따라 기존 리소스를 업데이트할 수 없는 경우도 있습니다. 이 경우 HTTP 상태 코드 409(충돌)를 반환하는 방안을 고려해야 합니다.

PATCH 메서드

클라이언트는 PATCH 요청을 사용하여 업데이트를 패치 문서의 형태로 기존 리소스에 보냅니다. 서버는 패치 문서를 처리하여 업데이트를 수행합니다. 패치 문서는 리소스 전체가 아니라 적용할 변경 내용만 설명합니다. PATCH 메서드에 대한 사양(RFC 5789)은 패치 문서에 대한 특정 형식을 정의하지 않습니다. 형식은 요청의 미디어 형식에서 유추해야 합니다.

Web API에 대한 가장 일반적인 데이터 형식은 JSON일 것입니다. 두 가지 주요 JSON 기반 패치 형식으로 JSON 패치 및 JSON 병합 패치가 있습니다.

이는 서버에 price를 업데이트하고 color를 삭제하고 size를 추가하도록 지시하지만 name 및 category는 수정되지 않습니다. JSON 병합 패치의 정확한 세부 정보는 RFC 7396을 참조하세요.

HTTP 상태 코드와 함께 PATCH 요청을 처리할 때 발생할 수 있는 일반적인 오류 조건

 

DELETE 메서드

삭제 작업이 성공하면 웹 서버는 프로세스가 성공적으로 처리되었지만 응답 본문에 추가 정보가 없음을 나타내는 HTTP 상태 코드 204(콘텐츠 없음)로 응답해야 합니다. 리소스가 없는 경우 웹 서버는 HTTP 404(찾을 수 없음)를 반환할 수 있습니다.

비동기 작업

때로는 POST, PUT, PATCH 또는 DELETE 작업을 완료하는 데 시간이 걸리는 처리가 필요할 수 있습니다. 처리 작업이 완료될 때까지 기다렸다가 클라이언트에 응답을 보내는 경우 허용되지 않는 수준의 대기 시간이 발생할 수 있습니다. 이 경우 비동기 작업을 수행하는 방안을 고려해 보아야 합니다. 요청 처리가 수락되었지만 아직 완료되지 않았음을 나타내는 HTTP 상태 코드 202(수락됨)를 반환합니다.

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

단일 URI를 통해 리소스 컬렉션을 표시하면 정보의 하위 집합만 필요할 때에도 애플리케이션이 대량의 데이터를 가져올 수 있습니다. 컬렉션 리소스에 대한 GET 요청은 다수의 항목을 반환할 가능성이 있습니다. 단일 요청에서 반환하는 데이터의 양이 제한되도록 Web API를 디자인해야 합니다. 검색할 최대 항목 수와 컬렉션의 시작 오프셋을 지정하는 쿼리 문자열을 지원하는 방안을 고려해 봅니다.

/orders?limit=25&offset=50

HATEOAS를 사용하여 관련 리소스 탐색

REST를 실행하는 기본적인 동기 중 하나는 URI 체계에 대해 미리 알고 있지 않아도 전체 리소스 집합을 탐색할 수 있어야 하기 때문입니다. 각 HTTP GET 요청은 응답에 포함된 하이퍼링크를 통해 요청된 개체와 직접 관련된 리소스를 찾는 데 필요한 정보를 반환해야 하며, 이러한 각 리소스에 대해 사용할 수 있는 작업을 설명하는 정보도 제공되어야 합니다. 이 원칙을 HATEOAS(Hypertext as the Engine of Application State)라 합니다. 시스템은 실질적으로 유한 상태 시스템으로서, 각 요청에 대한 응답은 한 상태에서 다른 상태로 바꾸는 데 필요한 정보를 포함하고 있으며, 다른 정보는 필요하지 않습니다.

참고 사이트