RESTful API in 15 minutes

Teach a Dog to REST from Apigee on Vimeo.

1. 좋은 API는 디자인에 의해 결정된다.

2. 단순한 것은 단순하게 유지함.

3. 두 개의 url이면 충분하다.

• 첫번째는 collection,   e.g. /dogs/

• 두번째는 element,    e.g. /dogs/bar

4. url에 동사가 필요하지 않은 이유는 HTTP에서 이미 PGPD (POST, GET, PUT, DELETE)이라는 (동사로 된) method를 제공하기 때문.

5. 사실 PGPD = CRUD (CREATE, READ, UPDATE, DELETE)로 이해하면 쉽다.

6. Convention이지만, url의 첫번째 부분 (collection)은 복수형으로 쓰는게 좋다. 예를 들면 dog 보다는 dogs의 의미적으로 더 알맞음.

7. url에 동사는 bad, 명사는 good

8. 그럼 훨씬 복잡한 것들은 url로 어떻게 처리하는가?

• 모든 detail은 물음표 (?) 뒤로 몰아넣는다.  e.g. /dogs?color=red&state=running&location=park

9. Pagination은 어떻게?

• limit과 offset을 이용 e.g. /dogs?limit=25&offset=50

10. Versioning은 어떻게?

• Facebook에서는 ?v=1.0의 형식을 이용: ?이후의 parameter는 optional이기 때문에 다른 개발자들이 포함을 하지 않을 경우 버전 업그레이드 전에는 괜찮지만 버전이 업그레이드 된 후에는 에러발생 가능성이 높음.

• 버전 자체를 url에 삽입. 1.0 혹은 1.1.1과 같은 floating point대신 정수를 이용. e.g. /v1/dogs

11. Pagination이 있다고 해도 너무 많은 정보를 가져온다. 그럼 내가 원하는 정확한 정보 단 하나만은 어떻게 보나?

• field를 query의 parameter로 넘긴다. e.g. /dogs?fields=name,color,location

12. Format은?

• 익숙한 기존의 [파일이름].[확장자] 형식을 이용 e.g. /dogs.json 혹은 /dogs/bar.json

13. top level domain과 sublevel domain은 어떻게?

• API gateway는 api.domain.com 

• 개발자용은 dev.domain.com