<div id="readability-page-1" class="page"><div><p data-ke-size="size16">zalando는 패션, 신발, 뷰티 부문을 판매하는 독일의 온라인 커머스 기업이다. zalando에서 작성한 Restful API 가이드의 몇가지 사례를 통해 좋은 API를 설계하는 방법을 정리해보고자 한다.&nbsp;</p>
<p data-ke-size="size16"><a href="https://opensource.zalando.com/restful-api-guidelines" target="_blank" rel="noopener">https://opensource.zalando.com/restful-api-guidelines</a></p>
<h2 data-ke-size="size26">설계 원칙</h2>
<h3 data-ke-size="size23">API가 첫번째이다.&nbsp;</h3>
<ul data-ke-list-type="disc">
<li>기능을 구현하기 전에 API를 미리 설계해야한다.</li>
<li>클라이언트와 동료들에게 사전에 API 리뷰를 받아야한다.&nbsp;</li>
</ul>
<p data-ke-size="size16">추가로 API를 설계할 때 고려해야하는 점은 다음과 같다.</p>
<ul data-ke-list-type="disc">
<li>도메인과 기능의 목적을 제대로 이해해야한다.</li>
<li>일반화된 리소스를 제공해야한다.&nbsp;
<ul data-ke-list-type="disc">
<li>특수한 사례별로 API를 제공하는 것은 피해야한다.&nbsp;</li>
</ul>
</li>
<li>API는 무엇을 제공하는지만 표현해야한다.
<ul data-ke-list-type="disc">
<li>어떻게 기능을 제공하는지는 API에 포함되면 안된다.</li>
<li>기능의 구현 방법은 추상화해야한다.</li>
</ul>
</li>
</ul>
<p data-ke-size="size16">이렇게 정의한 API는 Swagger처럼 표준화된 API 관리 도구로 제공하는 것이 좋다.&nbsp;</p>
<ul data-ke-list-type="disc">
<li>API 스펙을 한 곳에서 중앙관리 (SSOT: single source of truth)할 수 있다.</li>
<li>API 검색, GUI, 자동 품질 검사 등을 인프라 도구로 관리할 수 있다.</li>
</ul>
<hr contenteditable="false" data-ke-type="horizontalRule" data-ke-style="style2">
<h2 data-ke-size="size26">설계 원칙 사례</h2>
<h3 data-ke-size="size23">구분자로 리소스와 하위 리소스를 구분해야한다.</h3>
<p data-ke-size="size16">API에 하위 리소스를 표현해야하는 경우, 하위 리소스가 상위 리소스에 포함되도록 설계해야한다.&nbsp;</p>
<div>
<pre data-ke-language="java"><code>/resources/{resource-id}/sub-resources/{sub-resource-id}
/shopping-carts/de:1681e6b88ec1/items/1</code></pre>
</div>

<h3 data-ke-size="size23">복합키를 식별자 리소스로 표현하라.</h3>
<p data-ke-size="size16">복합키가 리소스를 가장 잘 표현하는 식별자인 경우, 슬래시를 사용하여 리소스 정보를 표현할 수 있다.</p>
<div>
<pre><code>/resources/{compound-key-1}[delim-1]...[delim-n-1]{compound-key-n}</code></pre>
</div>

<p>예시는 다음과 같다.</p>
<div>
<pre><code>/shopping-carts/{country}/{session-id}
/shopping-carts/{country}/{session-id}/items/{item-id}
/api-specifications/{docker-image-id}/apis/{path}/{file-name}
/api-specifications/{repository-name}/{artifact-name}:{tag}
/article-size-advices/{sku}/{sales-channel}</code></pre>
</div>
<p>그러나 복합키를 리소스 식별자로 공개한 경우, 다른 리소스 식별자를 추가하기 어려워진다는 점을 유의해야한다.</p>

<div>
<h3 data-ke-size="size23">Date/Time 속성은 _at 접미사로 끝난다.</h3>
<p data-ke-size="size16">boolean과 구분하기 위해, date/time 속성에는 _at 접미사를 붙인다.&nbsp;</p>
<pre id="code_1670859963002" data-ke-language="java" data-ke-type="codeblock"><code>created_at &lt;&lt; created
modified_at &lt;&lt; modified
occurred_at &lt;&lt; occurred
returned_at &lt;&lt; returned</code></pre>
</div>

<h2 data-ke-size="size26">boolean 타입을 null으로 반환하면 안된다.&nbsp;</h2>
<p data-ke-size="size16">boolean 타입인 값이 null을 반환하는 경우가 있다. boolean은 true 혹은 false만 반환해야한다.&nbsp;</p>
<p data-ke-size="size16">특정한 의미를 지닌 null 을 반환하는 경우, 별도로 정의된 상태 값을 반환해야한다.</p>
<p data-ke-size="size16">예를 들어, accepted_terms_and_conditions라는 속성이 있는 경우, <span><span>YES</span>, <span>NO</span>, <span>UNDEFINED</span>. 세가지 값을 가질 수 있다.&nbsp;</span></p>

<h2 data-ke-size="size26">비어있는 배열은 []으로 내려준다.</h2>
<p data-ke-size="size16">비어있는 배열을 null으로 반환하면 안된다. 반드시 빈배열로 내려야한다.</p>

<h2 data-ke-size="size26">Delete API에서 쿼리 파라미터를 사용할 수 있다.</h2>
<div>
<pre><code>DELETE /resources?param1=value1&amp;param2=value2...&amp;paramN=valueN</code></pre>
</div>
<p>삭제 요청에서 쿼리 파라미터가 사용될 수도 있다. 여기서 쿼리 파라미터는 리소스를 선택하기 위함이 아니라 필터링 목적으로 사용된다.&nbsp;</p>
<h2 data-ke-size="size26">Gzip 압축을 권장한다.</h2>
<p data-ke-size="size16">너무 많은 요청을 처리하느라, Gzip 압축 시간이 병목 현상을 일으키는게 아니라면&nbsp;</p>
<p data-ke-size="size16">요청 응답을 Gzip 으로 압축하는 것을 권장한다.</p>
<p data-ke-size="size16">그래야 네트워크를 통해 데이터를 빠르게 전달할 수 있고, 프론트가 더 빠르게 응답할 수 있다.&nbsp;</p>
<h2 data-ke-size="size26">응답 속성을 필터링하여, 응답 크기를 줄일 수 있다.</h2>
<p data-ke-size="size18">(1) 필터링을 하지 않은 케이스</p>
<pre><code>GET http://api.example.org/users/123 HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "cddd5e44-dae0-11e5-8c01-63ed66ab2da5",
  "name": "John Doe",
  "address": "1600 Pennsylvania Avenue Northwest, Washington, DC, United States",
  "birthday": "1984-09-13",
  "friends": [ {
    "id": "1fb43648-dae1-11e5-aa01-1fbc3abb1cd0",
    "name": "Jane Doe",
    "address": "1600 Pennsylvania Avenue Northwest, Washington, DC, United States",
    "birthday": "1988-04-07"
  } ]
}</code></pre>
<p data-ke-size="size18">(2) filter 파라미터로 필요한 속성만 추려낸 케이스</p>
<pre><code>GET http://api.example.org/users/123?fields=(name,friends(name)) HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json

{
  "name": "John Doe",
  "friends": [ {
    "name": "Jane Doe"
  } ]
}</code></pre>

<h2 data-ke-size="size26">추가로 읽어보면 좋은 REST API 자료&nbsp;</h2>
<ul data-ke-list-type="disc">
<li>Article:<span>&nbsp;</span><a href="https://www.thoughtworks.com/insights/blog/rest-api-design-resource-modeling">REST API Design - Resource Modeling</a></li>
<li>Article:<span>&nbsp;</span><a href="https://martinfowler.com/articles/richardsonMaturityModel.html">Richardson Maturity Model — Steps toward the glory of REST</a></li>
<li>Book:<span>&nbsp;</span><a href="https://www.amazon.de/Irresistible-APIs-Designing-that-developers/dp/1617292559">Irresistible APIs: Designing web APIs that developers will love</a></li>
<li>Book:<span>&nbsp;</span><a href="http://www.amazon.de/REST-Practice-Hypermedia-Systems-Architecture/dp/0596805829">REST in Practice: Hypermedia and Systems Architecture</a></li>
<li>Book:<span>&nbsp;</span><a href="https://leanpub.com/build-apis-you-wont-hate">Build APIs You Won’t Hate</a></li>
<li>Fielding Dissertation:<span>&nbsp;</span><a href="http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm">Architectural Styles and the Design of Network-Based Software Architectures</a></li>
</ul></div></div>

복세편살

zalando는 패션, 신발, 뷰티 부문을 판매하는 독일의 온라인 커머스 기업이다. zalando에서 작성한 Restful API 가이드의 몇가지 사례를 통해 좋은 API를 설계하는 방법을 정리해보고자 한다. 
https://opensource.zalando.com/restful-api-guidelines
설계 원칙
API가 첫번째이다. 
기능을 구현하기 전에 API를 미리 설계해야한다.
클라이언트와 동료들에게 사전에 API 리뷰를 받아야한다. 
추가로 API를 설계할 때 고려해야하는 점은 다음과 같다.
도메인과 기능의 목적을 제대로 이해해야한다.
일반화된 리소스를 제공해야한다. 
특수한 사례별로 API를 제공하는 것은 피해야한다. 
API는 무엇을 제공하는지만 표현해야한다.
어떻게 기능을 제공하는지는 API에 포함되면 안된다.
기능의 구현 방법은 추상화해야한다.
이렇게 정의한 API는 Swagger처럼 표준화된 API 관리 도구로 제공하는 것이 좋다. 
API 스펙을 한 곳에서 중앙관리 (SSOT: single source of truth)할 수 있다.
API 검색, GUI, 자동 품질 검사 등을 인프라 도구로 관리할 수 있다.
설계 원칙 사례
구분자로 리소스와 하위 리소스를 구분해야한다.
API에 하위 리소스를 표현해야하는 경우, 하위 리소스가 상위 리소스에 포함되도록 설계해야한다. 
/resources/{resource-id}/sub-resources/{sub-resource-id}
/shopping-carts/de:1681e6b88ec1/items/1
 
복합키를 식별자 리소스로 표현하라.
복합키가 리소스를 가장 잘 표현하는 식별자인 경우, 슬래시를 사용하여 리소스 정보를 표현할 수 있다.
/resources/{compound-key-1}[delim-1]...[delim-n-1]{compound-key-n}
 
예시는 다음과 같다.
/shopping-carts/{country}/{session-id}
/shopping-carts/{country}/{session-id}/items/{item-id}
/api-specifications/{docker-image-id}/apis/{path}/{file-name}
/api-specifications/{repository-name}/{artifact-name}:{tag}
/article-size-advices/{sku}/{sales-channel}
그러나 복합키를 리소스 식별자로 공개한 경우, 다른 리소스 식별자를 추가하기 어려워진다는 점을 유의해야한다.
 
Date/Time 속성은 _at 접미사로 끝난다.
boolean과 구분하기 위해, date/time 속성에는 _at 접미사를 붙인다. 
created_at << created
modified_at << modified
occurred_at << occurred
returned_at << returned
 
boolean 타입을 null으로 반환하면 안된다. 
boolean 타입인 값이 null을 반환하는 경우가 있다. boolean은 true 혹은 false만 반환해야한다. 
특정한 의미를 지닌 null 을 반환하는 경우, 별도로 정의된 상태 값을 반환해야한다.
예를 들어, accepted_terms_and_conditions라는 속성이 있는 경우, YES, NO, UNDEFINED. 세가지 값을 가질 수 있다. 
 
비어있는 배열은 []으로 내려준다.
비어있는 배열을 null으로 반환하면 안된다. 반드시 빈배열로 내려야한다.
 
Delete API에서 쿼리 파라미터를 사용할 수 있다.
DELETE /resources?param1=value1&param2=value2...&paramN=valueN
삭제 요청에서 쿼리 파라미터가 사용될 수도 있다. 여기서 쿼리 파라미터는 리소스를 선택하기 위함이 아니라 필터링 목적으로 사용된다. 
Gzip 압축을 권장한다.
너무 많은 요청을 처리하느라, Gzip 압축 시간이 병목 현상을 일으키는게 아니라면 
요청 응답을 Gzip 으로 압축하는 것을 권장한다.
그래야 네트워크를 통해 데이터를 빠르게 전달할 수 있고, 프론트가 더 빠르게 응답할 수 있다. 
응답 속성을 필터링하여, 응답 크기를 줄일 수 있다.
(1) 필터링을 하지 않은 케이스
GET http://api.example.org/users/123 HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
  "id": "cddd5e44-dae0-11e5-8c01-63ed66ab2da5",
  "name": "John Doe",
  "address": "1600 Pennsylvania Avenue Northwest, Washington, DC, United States",
  "birthday": "1984-09-13",
  "friends": [ {
    "id": "1fb43648-dae1-11e5-aa01-1fbc3abb1cd0",
    "name": "Jane Doe",
    "address": "1600 Pennsylvania Avenue Northwest, Washington, DC, United States",
    "birthday": "1988-04-07"
  } ]
}
(2) filter 파라미터로 필요한 속성만 추려낸 케이스
GET http://api.example.org/users/123?fields=(name,friends(name)) HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
  "name": "John Doe",
  "friends": [ {
    "name": "Jane Doe"
  } ]
}
 
추가로 읽어보면 좋은 REST API 자료 
Article: REST API Design - Resource Modeling
Article: Richardson Maturity Model — Steps toward the glory of REST
Book: Irresistible APIs: Designing web APIs that developers will love
Book: REST in Practice: Hypermedia and Systems Architecture
Book: Build APIs You Won’t Hate
Fielding Dissertation: Architectural Styles and the Design of Network-Based Software Architectures

Zalando 사례를 통해 REST API 가이드 살펴보기

댓글