[API] 개발자들이 사랑할 수 있는 API 설계방법 from Web API Design - Crafting Interfaces that Developers Love.

출처 : Web API Design - Crafting Interfaces that Developers Love.

개발자들이 사랑할 수 있는 API 설계방법

from Web API Design - Crafting Interfaces that Developers Love.

- 이 글은 Web API Design - Crafting Interfaces that Developers Love 라는 소책자의 내용을 요약 정리한 내용입니다.

Introduction

- 이 책은 개발자들이 좋아할 수 있는 검증된, 실제 사용되는 Web API 를 설계하는 데 있다.

- 여기서는 REST 를 design source 로 다루는데, 엄격한 기준을 요구하지 않기 때문에 확장성이 좋다는 장점이 있다.

- 개발자는 API 의 고객이다. 좋은 API 는 개발자들이 얼마나 빨리 이해할 수 있고, 쉽게 사용할 수 있느냐다.

Are you a Pragmatist or a Restafarian?

- RESTifarian 은 Roy T. Fielding의  software architectural style 을 광적으로 지지하는 사람들을 지칭한다. 광적으로 지지하기 때문에 더 좋은 방법에 대한 모색을 비판하곤 한다.

- 이 책에서의 API design 접근방식은 outside-in 으로 우리가 API 를 통해 무엇을 성취하려고 하는가? 라는 질문으로 시작한다. 그리고 본질적으로 API design은 개발자의 사용 관점에서 개발해야 한다.

- pragmatic REST 는 개발자의 생산성과 성공적 사용을 극대화 하는 API 를 말한다. 
( pragmatic 사전적 의미는 실용주의 )

Nouns are good; verbs are bad

- 기본 중의 기본은 간단하게 만드는 것이다.

Keep your base URL simple and intuitive

- affordance 는 design 요소로 문서(또는 글)없이 어떻게 사용할 수 있는지 파악하도록 하는 것을 말한다.

- 문서화 할 필요없이 의도와 의미를 파악하여 사용될 수 있는 API가 가장 좋은 design이다.

- Web API design 을 하는 데 있어 한 resource 에 대해 오직 2개의 base URL 을 제공해야만 한다.

  하나는 복수( /books )이고, 하나는 단수( /books/132 ) 이다. 

Keep verbs out of your base URLs

- 동사를 사용하게 되면 목적어의 종류가 무한대로 늘어날 수 있기 때문에 직관적인 API 가 되지 않는다.

Use HTTP verbs to operate on the collections and elements

- POST, GET, PUT, DELETE 를 CRUD 로 매핑해서 동사로 사용해라.

Summary

- 한개의 resource 에 대해 2개의  base url 만 사용해라. ( 복수 & 단수 접근 )

- base URL에서 동사는 빼라.

- HTTP verbs 를 사용해라.

Plural nouns and concrete names

- plural 을 써도 되고 singular 를 써도 되지만, 보통은 plural 을 사용한다. GET 이 주 타겟이기 때문이다. 문제는 둘을 혼합해서 사용할 경우이다.

Concrete names are better than abstract

- 12~24개의 URL resource 를 제공하는 것이 좋다. 이에 따라서 abstraction level 을 조절하는 것이 좋다. 가급적이면 concrete 한 것이 좋다.

Summary

- plural & concrete name 이 권장된다.

Simplify associations - sweep complexity under the '?'

Associations

- 한 자료는 다른 자료와 보통 관련이 있다. GET /owners/1234/books 와 같이 연결되면 경우의 수가 늘어나며 API 가 더 복잡해지기 쉽다.

Sweep complexity behind the '?'

- ? 뒤에 조건문을 써줌으로써 Base URL API 들을 간단히 해라. 예를 들어 GET /books?color=red&state=borrowed

Summary

- API 는 직관적이고 심플하게 만들어라. 그리고 다른 자료와의 연결은 ? 뒤에 조건절을 달아주는 것을 잘 활용해서 API 를 심플하게 하는데 일조하라.

Handling erros

Why is good error design especially important for API designers?

- API 사용자 측에서는 API 서버쪽이 black box 이다. error 가 API 의 내용을 이해하게 만들어준다.

How to think about errors in a pragmatic way with REST?

A couple of best practices

- HTTP status code 를 사용해라. 그러나 8~10개 정도로 큰 범주로 나누어 사용해라. ( 총 70개 )

- success( 200 ), client error( 400 ), server error (500).

- created( 201 ), not modified( 304 ), not found ( 404 ), unauthorized( 401 ), forbidden( 403 )
- 에러 메세지는 가능한한 자세하게 기술하고, status code 와 그에 대한 설명을 함께 제공하라.

Summary

- error를 묘사하여 장황하게 써라. 그리고 무엇이 error 를 초래했는지 가능한한 많은 힌트를 주어라. payload 때문에 싫다면 에러를 자세히 묘사한 링크를 제공하라.

Tips for versioning

- 무조건 version 을 만들어라. 그러나 소수점단위로는 안 가는 것이 좋다. 그리고 version 을 optional 로 주지 말아라.

How to think about version numbers in a pragmatic way with REST?

- version 은 v 와 함께 시작하는 것이 좋다. 그리고 highest scope 에 넣도록 하자.

- 소숫점 없이 정수로만 사용하자. 소수점이 들어가면 API 가 자주 바뀌는 것을 암시한다. ( 하지만 그러면 안된다. )

- How many versions should you maintain? :  적어도 한 개의 전 버전을 유지해라.

Should version and format be in URLs or headers?

- 사실 디자인상으로는 Header 에 version 정보를 넣는 것이 더 옳다. 하지만 브라우저 해킹이슈가 있다. 

- logic 이 바뀔 수 있는 API라면, URL 안에 버전을 넣는 것이 좋고, 그렇지 않다면 header 에 넣는 것이 좋다.

Pagination and Partial Response

- partial response 는 개발자에게 원하는 정보만을 제공할 수 있다.

- /people:( a,b )  또는 /people?fields=a, b 와 같이 comma 구분하여 field 명을 써준다.

Make it easy for developers to paginate objects in a database

- database 의 모든 정보를 return 하는 것은 "거의 대부분" 안 좋은 것이다.

- offset, limit 를 두어 paging 해서 보내곤 한다.

- 추가적으로 metadata 를 제공하는 것이 좋은 방법이다.

- default 값은 offset=0, limit=10 이 경험상 좋다.
  ( 사실 이는 data size, 앱 디자인 등에  따라 달라진다. )

 

Summary

- comma 로 구분된 field 값을 받아 부분정보만을 제공하라.

- limit & offset 을 제공하여 page 된 데이터를 제공하라.

What about responses that don't involve resources?

- non resource scenario 가 있을 수 있다. 예를 들면 통화계산, 세금 계산 등의 calculation, translate, convert 등이 그 예이며, 이런 경우 보통 동사를 사용한다. 

- non-resource scenario 는 API doc 에 잘 기술해야 한다.

Supporting multiple formats

- format 내용을 URL 에도, header 에도 담을 수 있는데, 보통 URL 에 담는다. ( url 과 header 가 conflict 날 경우 어떻게 되는지를 문서에 반드시 기술해야 한다. )

- /books/323.json 또는 /books/323?type=json 등의 방법이 주로 사용되는데, .json 방법이 가장 낫다.

- default format 은 JSON이다.

What about attribute names?

- JSON을 기본으로 사용하고, JavaScript convention 을 attribute name 으로 잡는다.

- JavaScript convention 은 CamelCase

Tips for search

- 여러 resource 를 통틀어 search 할 경우에는 동사와 query 문을 사용하는 것이 좋다.

- 예를 들어 /search?q=dictionary+language

- scoped search 의 경우는 다음과 같이 가능하다. /library/2324/books?q=dictionary+language

Consolidate API requests in one subdomain

- 목적에 따라 여러개의 domain 으로 나눌 수 있지만, 하나로 접근하는 것이 가장 좋다.
  ( 예를 들어 api.abc.com, locationapi.abc.com )

- browser 를 사용하는 경우라면 redirect 를 사용할 수도 있다.

Tips for handling exceptional behavior

- flash 의 경우 중간에 response 를 intercept 하여 처리하는 경우가 있다. 이럴 경우 제대로 된 error message 를 받을 수 없어서, 특정 parameter 를 option 으로 주면 무조건 200 으로  return 이 오게 하는 경우도 있다. 이 경우에는 HTTP response 안의 message 에서 error 내용을 확인할 수 있다.

- client 가 HTTP method 를 부분적으로 지원할 경우에는( 예를 들어, GET, POST만 지원한다면.. ) , method 를 optional 로 주어(method=delete) 해당 method 로 처리한다. 이 때 보통 default 는 GET 으로 둔다.

Authentication

- 최신 인증기술을 사용하라. ( 글의 저자가 글을 쓸 당시에는 OAuth 2.0 )

Chatty APIs

- chatty 한 API 를 만들지 말아라.

- 여러 정보를 통합해서 주고자 할 때는, 먼저 기본 API 디자인을 맞춘 후, shortcut 을 제공하라.