RESTful API 디자인(네이밍)

개발자에 사랑받는 API 만들기

http://www.mimul.com/pebble/default/2012/08/07/1344315512542.html

 

1.     기본 URL에는 동사가 아닌 명사를 사용하며, 리소스마다 2개의 기본 URL을 유지하자

-       심플한 것이 가장 보기 좋다

        Ex) /dogs(Collection), /dogs/1234(Element)

 

2.     HTTP 동사(POST, GET, PUT, DELETE)를 사용해 집합(컬렉션)이나 개별 요소를 오퍼레이션 하자

-       POST(create), GET(read), PUT(update), DELETE(delete)를 명심하자.

-       결국 Resource(collection) / {Key}(element) 형식으로 집합과 요소를 구분하자

 

3.     복수형 명사와 구체적인 이름을 사용하라.

-       단수보다 복수 형태를 사용하는 편이, 그리고 추상적인 이름보다 구체적인 이름을 사용하는 편이 직관적인 API다.

        Ex) Foursquare : /checkins, GroupOn : /deals, Zappos : /Product

 

4.     자원 간의 관계를 간단하게 하여 URL 계층이 깊어지는 것을 피하자

-       자원간의 관계, 매개 변수 속성과 같은 복잡한 것은 HTTP 물음표를 뒤에 가지고 가자.

        Ex) GET /owners/5678/dogs, GET /dogs?color=red&state=running&location=park

 

5.     오류 처리를 명확하게 해라.

-       HTTP 상태코드를 정하고(많아도 안좋음), 개발자들을 위한 오류 메시지 정의, 상세 정보 링크 등을 넣어주면 좋다.

200 - OK
400 - Bad Request
500 - Internal Server Error
201 - Created
304 - Not Modified
404 - Not Found
401 - Unauthorized
403 - Forbidden

-       code, message, more_info 필드를 두어서 결과값을 먼저 파악할 수 있도록 한다.

예) {"status" : "401", "message":"Authenticate","code": 20003, 
 "more info": "http://www.twilio.com/docs/errors/20003"}

 

6.     버전 관리를 해라.

-       접두사 v로 버전을 지정하고 1계충에 두자.

-       인터페이스로서의 구현이 아님을 강조하기 위해 간단한 정수를 사용하자. 버전 일련번호는 소수점 쓰지 마라.

-       필요시 헤더에 버전을 디자인 할 수 도 있다 (단점은 개발자들이 잊을 수 있다.)

-       Ex) GET /v1/dogs

 

7.     부분적 응답과 페이징 처리를 하라.

-       리턴해 달라는 필드를 지정하려면(부분 응답) 쉼포로 구분된 목록을 사용하자.

        Ex) /dogs?fields=name,color,location

-       페이징을 할 경우 상대 위치(offset)와 범위(limit)를 사용, 기본 값은 limit=10&offset=0을 사용한다

        Ex) /dogs?limit=25&offset=50

 

8.     데이터 베이스에 없는 자원에 대한 응답일 경우 동사를 사용하라

-       리소스가 아닌 응답을 전송하는 경우 명사가 아니라 동사를 사용하는 것이 알기 쉽다

-       계산(Calculate), 번역(Translate), 변환(Convert) 등의 경우처럼 알고리즘 계산이나 번역, 환율 변환 등에 요청이 올경우 명사가 아니라 동사를 사용하라.

        Ex) /convert?from=EUR&to=CNY&amount=100

 

9.     다양한 형식(컨텐트 타입)을 지원하는 경우 도트 형식의 서식으로 하라.

-       JSON과 XML과 같이 API 다른 응답형식을 지원하는 것을 추천한다.

-       기본 형식은 JSON이다.

-       ACCEPT 헤더에 타입을 지정하거나 URL속에 type 매개변수를 사용할 수 있다. 권장 방식은 명사.type(도트 형식의 서식)으로 하는게 낫다.

        Ex) dogs.json, /dogs/1234.json

 

10.   속성(attribute)의 네이밍은 Javascript의 관습을 따르고 카멜 케이스를 사용하자.

-       기본값으로 JSON을 사용하고, 속성의 이름은 Javascript의 관습을 따른다. 중간 부분에 대문자를 사용(카멜 케이스)

        Ex) "createdAt": 1320296464

 

11.   검색 팁

-       전체 검색은 동사 “search”와 쿼리 매개 변수”q”를 사용하자

        Ex) /search?q=fluffy+fur

-       범위 한정 검색은 /리소스/리소스 ID/리소스?q=XXX(리소스 ID가 5678 인 주인의 개를 검색) 형태로 한다.

        Ex) /owners/5678/dogs?q=fluffy+fur

-       도트 형식의 서식을 사용하여 검색 결과 형식을 지정하자.

        Ex) /search.xml?q=fluffy+fur

 

12.   하위 도메인의 독립적인 API 요청 처리는 여러 개를 만들지 말고 통일하라.

- 여러 기능적으로 독립된 url을 여러개 만들지 말고 모든 API 요청을 하나의 API 하위 도메인에 정리하자. api.company.com 같은 것을 사용하는 것이다.

- developers.company.com 같은 개발자 전용 포털을 만들자.

- 사용자가 브라우저에서 API 하위 도메인을 여는 등 요청에 대한 원하는 정보가 없다면 개발자 포털로 리다이렉트 해라.

 

13.   예외 처리를 위한 팁

-       클라이언트가 HTTP 오류 코드를 차단하는 경우(Adobe Flash 경우), 응답을 클라이언트에서 먹어버림으로 응용 프로그램 개발자가 오류 코드를 차단하는 기회가 없어진다. 그래서 트위터처럼 suppress_response_codes가 있으면 무조건 200으로 리턴하게 한다.

-       클라이언트가 지원하는 HTTP 메소드가 제한되는 경우 URL에서 method형태로 호출하게 한다. 

  예) Create : /dogs?method=post, Read : /dogs, 
 Update : /dogs/1234?method=put&location=park, 
 Delete : /dogs/1234?method=delete

14.   권한 관리(OAuth)는 2.0을 사용하라.

-       OAuth 1.0a보다 2.0을 사용하라. 더 안전하고 웹과 모바일 모두 사용자에게 더 나은 경험을 제공한다.

 

15.   API 상에서 요청을 구성해보면 아래와 같다

-       AL라는 갈색 개를 생성

POST /dogs
name=Al&furColor=brown
응답
200 OK
{
"dog": {
"id": "1234"
"name": "Al"
"furColor": "brown"
}
}

-       Al의 이름을 Rover로 수정

PUT /dogs/1234
name=Rover
응답
200 OK
{
"dog": {
"id": "1234"
"name": "Rover"
"furColor": "brown"
}
}

-       특정 개에 관라여 조회

GET /dogs/1234
응답
200 OK
{
"dog": {
"id": "1234"
"name": "Rover"
"furColor": "brown"
}
}

-       모든 개에 관해 조회

GET /dogs
응답
200 OK
{
"dogs":
{ "dog": {
"id": "1233"
"name": "Fido"
"furColor": "white"}}
{ "dog": {
"id": "1234"
"name": "Rover"
"furColor": "brown"}}
"_metadata":
[{ "totalCount": 327 "limit"25 "offset": 100}]
}

-       Rover 개 삭제

DELETE / dogs/1234
응답
200 OK

 

16.   수다 API 지양하자

-       간단한 응용 프로그램을 구축하는데, 여러 번의 서버 API 호출을 해야 하는 수다스러운 API는 지양해라.

-       완전한 RESTful API를 만들고, 필요에 따라 단축키 및 합성 응답을 제공하는 것을 추천한다.

 

17.   SDK로 API를 보완하라

-       자기 모순없이 표준에 기초하고 있고, 충분히 문서화 되어 있고, 예제도 충분히 있다면 SDK가 필요 없을 수도 있다. 하지만 API 프로바이더는 샘플 코드 라이브러리, 소프트웨어 개발 키트 API를 보충하는 것을 추천한다.

-       도메인 지식에 의해 API가 변경되어서는 안된다. SDK를 통해 API를 보완해라

-       SDK는 낮은 품질, 비효율적인 코드를 줄여준다.

 

18.   API Facade Pattern을 API 설계에 고려해라.

- 인터페이스와 API구현체 사이의 가상 레이어가 존재한다.

- 구현은 세 가지 기본적인 단계로 구성된다.

- 이상적인 API를 디자인하라 - URL, 요청 파라미터, 응답, 페이로드, 헤더, 쿼리 파라미터 등. API 디자인은 일관되어야 한다.

- 데이터 스텁을 사용하여 디자인을 구현하라. 

  이제 API가 내부 시스템에 연결되기 전에 응용 프로그램 개발자는 API를 사용할 수 있으며, 피드백을 줄 수 있다.

- 퍼사드와 내부 시스템 사이에서 중개자 역할 또는 통합을 한다.