REST: Definições e Boas Práticas

Apresentação realizada como parte da iniciativa VTEX Tech Talks.
--
Presentation made as a part of the VTEX Tech Talks initiative.

Transcript

1. Alex Tercete tercete@vtex.com.br REST Definições e Boas Práticas
2. HTTP Firulas +
3. HTTP Recursos +
4. Recursos
5. Dog https://www.flickr.com/photos/mcpig/2203669161
6. POST /dogs GET /dogs/:id PUT /dogs/:id DELETE /dogs/:id
7. dog vs. dogs
8. POST /dogs/:id/feed POST /dogs/:id/throwBone GET /dogs/:id/showOwner POST /dogs/:id/takeOut
9. Verbos NÃO
10. Substantivos SIM
11. feed throwBone showOwner takeOut food  meal bone  game owner walk  exercise
12. POST /dogs/:id/meals POST /dogs/:id/games GET /dogs/:id/owners POST /dogs/:id/exercises
13. GET /dogs/getByFurColor GET /dogs/getByOwner
14. Query String
15. GET /dogs?furColor=:color GET /dogs?owner=:owner
16. GET /dogs?furColor=:color GET /owners/:id/dogs
17. Verbos
18. GET POST PUT DELETE id id ? id id id id
19. Cria Obtém Altera Remove GET POST PUT DELETE
20. Method Definitions RFC2616, Seção 9 http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html
21. Status Code
22. Redirection Successful Client Error Server Error 2XX 3XX 4XX 5XX
23. Não é aqui. Tá tudo BEM! Você tá MAL! Eu tô MAL! 2XX 3XX 4XX 5XX
24. http://httpstatusdogs.com/
25. http://httpstatusdogs.com/
29. HTTP/1.1 201 Created Location: /dogs/Snoopy POST /dogs HTTP/1.1 Content-Type: application/json { "name": "Snoopy" }
30. HTTP/1.1 301 Moved Permanently Location: /composers/Beethoven GET /dogs/Beethoven HTTP/1.1
31. HTTP/1.1 401 Unauthorized WWW-Authenticate: Basic GET /dogs HTTP/1.1
32. HTTP/1.1 405 Method Not Allowed Allow: GET, POST DELETE /dogs HTTP/1.1
33. Status Code Definitions RFC2616, Seção 10 http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
34. Cache
35. HTTP/1.1 200 OK Cache-Control: private, max-age=300 Expires: Tue, 18 Mar 2014 19:00:00 GMT ETag: 50780f47f6839d47d60bc4555ee00c3f GET /dogs HTTP/1.1
36. HTTP/1.1 304 Not Modified Cache-Control: private, max-age=300 Expires: Tue, 18 Mar 2014 19:00:00 GMT ETag: 50780f47f6839d47d60bc4555ee00c3f GET /dogs HTTP/1.1 If-None-Match: 50780f47f6839d47d60bc4555ee00c3f
37. Caching in HTTP RFC2616 http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html
38. Versionamento
39. GET /v1/dogs HTTP/1.1 GET /dogs HTTP/1.1 X-VTEX-Zoo-Version: v1 GET /dogs HTTP/1.1 Accept: application/vnd.vtex.zoo-v1+json Rota Cabeçalho Proprietário Cabeçalho Padrão
40. Autenticação
41. GET /dogs HTTP/1.1 Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== GET /dogs HTTP/1.1 Authorization: AWS AKIAIOSFODNN7EXAMPLE:fr...Dzg= GET /dogs HTTP/1.1 X-VTEX-Api-AppKey: some-key X-VTEX-Api-AppToken: 5Om3tOkE|\| Padrão Proprietária Muito Proprietária
42. The OAuth 2.0 Authorization Framework RFC6749 http://tools.ietf.org/html/rfc6749
43. Tratamento de Erros
44. HTTP/1.1 401 Unauthorized WWW-Authenticate: Basic Content-Type: application/json { “errorCode”: “auth.invalid_credentials”, “message”: “Credenciais inválidas”, “help”: “http://docs.vtex.com/api/authentication” }
45. HTTP/1.1 400 Bad Request Content-Type: application/json { “errorCode”: “checkout.invalid_order”, “message”: “Dados do pedido inválidos”, “reasons”: { “id”: “É obrigatório” } }
46. Hypermedia
47. HTTP/1.1 200 OK Content-Type: application/json { “name”: “Snoopy” “owners”: [{ “name”: “Charlie Brown” }] } GET /dogs/Snoopy HTTP/1.1 Accept: application/json
48. HTTP/1.1 200 OK Content-Type: application/json { “name”: “Snoopy”, “owners”: { “href”: “/dogs/Snoopy/owners” } } GET /dogs/Snoopy HTTP/1.1 Accept: application/json
49. Virtualização
50. Camada de Virtualização da API API API API Aplicação
51. Considerações Finais
52. Resumo • REST = HTML + Recursos • Verbos, não! Substantivos, sim! • Status Codes: – 20[014], 30[124], 4(0[13459]|2[29]), 50[03] • Cache • Versionamento: – Accept • Autenticação: – OAuth 2.0 • Hypermedia: – href • Virtualização
53. Bons exemplos • http://developer.github.com/v3/ • http://www.twilio.com/docs/api/rest • https://developer.paypal.com/webapps/develop er/docs/api/ • http://developer.netflix.com/docs
54. Maus exemplos • http://www.flickr.com/services/api/request.rest. html • https://dev.twitter.com/docs/api/1.1 • https://developers.facebook.com/docs/graph- api/reference
55. Referências • http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm • Apigee – https://blog.apigee.com/detail/restful_api_design_nouns_are_good_verbs_are_bad – https://blog.apigee.com/detail/restful_api_design_plural_nouns_and_concrete_name s – https://blog.apigee.com/detail/simplify_associations_sweep_complexities_under_the _http – https://blog.apigee.com/detail/restful_api_design_what_about_errors – https://blog.apigee.com/detail/restful_api_design_chatty_apis – https://blog.apigee.com/detail/restful_api_design_complement_with_sdk – https://blog.apigee.com/detail/restful_api_design_api_virtualization
56. Referências (2) • http://blogs.burnsidedigital.com/2013/07/whats-a-rest-api/ • Steve Klabnik – http://blog.steveklabnik.com/posts/2011-07-03-nobody-understands-rest-or- http – http://blog.steveklabnik.com/posts/2011-08-07-some-people-understand- rest-and-http – http://blog.steveklabnik.com/posts/2012-02-23-rest-is-over – http://blog.steveklabnik.com/posts/2012-02-13-an-api-ontology – http://timelessrepo.com/haters-gonna-hateoas • http://barelyenough.org/blog/2008/05/versioning-rest-web-services/ • http://www.mobify.com/blog/beginners-guide-to-http-cache-headers/
57. Alex Tercete tercete@vtex.com.br Obrigado!