RESTful API Design 읽고

slide 2nd : http://www.slideshare.net/apigee/restful-api-design-second-edition, 2011

video 2nd : http://www.youtube.com/watch?v=QpAhXa12xvU&list=TL9xhGrr5Tun8, 2011

side 3rd : http://www.slideshare.net/apigee/api-design-3rd-edition, 2013

아래 내용은 2nd 기준에서 3rd를 약간 추가.

지금보니 내가 2012년에 RESTfull 관련해서 쓴 글이 있더라는...http://blog.daum.net/rollin/8097009

[ 목표 ]
- 실용적인 API 만들기
- 왜? The API's job is to make the developer as successful as possible.  
- 정확히 REST한 API를 만드는 것이 아니라, 실용적으로 만들려다보니 REST를 가져다 쓴다.

[ two base URLs ]
- The first for collection. ex) /dogs
- The second is for an element. ex) /dogs/1234

[ singular? plural? ]
- 어느것을 쓰든 한가지만 써라.
- 치: 발표자는 plural을 선호하는 듯 한데...한쿡인으로써는 singular가 나을듯.
ㄴ 일단 잘못된 plural을 쓸 가능성이 높고, 어차피 singular를 써도 어색하다 생각 안함. => low risks.

[ HTTP method 활용 ]
- resource에 대한 CRUD는 POST/GET/PUT/DELETE로 처리.
- 아래 테이블이 권장사항인데, REST 논문하고는 좀 다르다. 이 포인트에서 너무 짜치게 RESTful에 목매지 말란 얘기를 하는 듯.
- RESTful에서의 POST/GET/PUT/DELETE는 예전 글에...http://blog.daum.net/rollin/8097009

- 치: 경우에따라 client에서 ID를 지정해서 create해야 하는 경우가 있는데... 이럴때는 element에 POST를 호출하는게 깔끔할듯. spec상 element에 PUT하는게 더 정확한데, 실무적으로 New와 Update를 하나의 method로 처리해버리면 client가 혼란스러워할 위험이 있더라...

[ relationship ]
- /oweners/123/dogs

[ error code ]
- status code!!
ㄴ important 8 : 200, 201, 304, 400, 401, 403, 404, 500
- more_info : 이 에러에 관한 정보를 얻을 수 있는 링크. 사람들이 알아서 관련 정보를 업데이트 할것이다.


[ 페이징 ]
- offset & limit : 기본적으로 ok. offset이 너무 커지면?? => from & limit로 제한.
- from & limit : offset보다 빠르게 시작점을 찾을 수 있음. 먼 과거를 지원하지 않을경우 없어도 될듯..

[ non-resource-y type? ]
- convert, translate, calculate...
- CRUD가 아닌 verb.

[ 기타 ]
- count : /dog/count = count of all dog in the dbms.
- /foo/123?suppress_response_codes=true : 무조건 200 ok. body에 추가 정보 제공.
- api.foo.com=API서비스 / developers.foo.com=개발자사이트

[ 요약 ]
- Be RESTful
- only 2 base URLs (?)
- No verbs (convert는??)
- Use nouns as plurals (어느쪽이든 상관없다 해놓고 마지막엔 복수.)
- Concrete over abstract : /animal(x) /dog(o)
- For JSON follow JavaScript conventions : created_at(x) createdAt(o)
- Sweep complexity behind the '?'
- Borrow from leading APIs : twitter, facebook, google, salesforce...
- Account for exceptional clients : supress_error_code
- Add Virtualization layer

[ 사족 ]
- resource name에 대해서는 1depth만으로 충분하다는 입장인데...동음이의어 등의 이슈를 생각해보면 될런지 모르겠다...
ㄴ 고유명사는 value라고 하더라도, 세상에는 dog 하나에도 수많은 category가 있는데... 어디까지를 class로 하고 어디까질 instance로 할지는 여전히 문제..
ㄴ 그런데...contextPath가 있는 것을 생각하면..엄밀히는 2depth부터 시작인거고, 1depth는 서비스 자체가 된다.
   어차피 하나의 서비스는 하나의 문제 해결을 위해 사용한다고 놓고 보면...application에서는 1depth만으로 resource 표현이 가능할듯?
- REST를 FM으로 쓸것이 아니라면...각 method에 대해 여러가지 변종을 허용해야겠지...결국 api call해보고 결과 메시지로 학습하는 수 밖에...
ㄴ 게다가 경험상 api client에서 ID를 지정해서 요청하는 경우도 있는데, 이런 경우는 element에 POST가 적절한것 아닐까?