Boas práticas em REST APIs

Conceitos sobre HTTP/RESTful e algumas boas práticas de como projetar sua API de forma consistente e legível.

Transcript

1. Boas Boas práticas práticas em em REST APIs REST APIs
2. Diego Garcia Diego Garcia /author/diego-garcia.html http://codeforcloud.info/ drgarcia1986 @drgarcia1986 /drgarcia1986
3. HTTP e REST HTTP e REST • HTTP é um protocolo de requisição- resposta. • REST é um conjunto de princípios que definem como HTTP e URIs devem ser usados. HTTP: Hypertext Transfer Protocol REST: Representational State Transfer
4. GET /products/ HTTP/1.1 User-Agent: curl/7.35.0 Host: localhost:5000 Accept: */* Request Request curl -v localhost:5000/products/
5. GET /products/ HTTP/1.1 User-Agent: curl/7.35.0 Host: localhost:5000 Accept: */* Request Request curl -v localhost:5000/products/ VERBO VERBO
6. GET /products/ HTTP/1.1 User-Agent: curl/7.35.0 Host: localhost:5000 Accept: */* Request Request curl -v localhost:5000/products/ URI URI
7. GET /products/ HTTP/1.1 User-Agent: curl/7.35.0 Host: localhost:5000 Accept: */* Request Request curl -v localhost:5000/products/ Formatos aceitos Formatos aceitos
8. HTTP/1.1 200 OK CONTENT-TYPE: application/json CONTENT-LENGTH: 83 [{"name":"smartphone","price":500.0, "id":1}, {"name":"tablet","price":300.0,"id":2}] Response Response curl -v localhost:5000/products/
9. HTTP/1.1 200 OK CONTENT-TYPE: application/json CONTENT-LENGTH: 83 [{"name":"smartphone","price":500.0, "id":1}, {"name":"tablet","price":300.0,"id":2}] Response Response curl -v localhost:5000/products/ Status Code Status Code
10. HTTP/1.1 200 OK CONTENT-TYPE: application/json CONTENT-LENGTH: 83 [{"name":"smartphone","price":500.0, "id":1}, {"name":"tablet","price":300.0,"id":2}] Response Response curl -v localhost:5000/products/ Formato da resposta Formato da resposta
11. HTTP/1.1 200 OK CONTENT-TYPE: application/json CONTENT-LENGTH: 83 [{"name":"smartphone","price":500.0, "id":1}, {"name":"tablet","price":300.0,"id":2}] Response Response curl -v localhost:5000/products/ Corpo da resposta Corpo da resposta
12. Verbos Verbos • GET: Ler um recurso ou uma coleção. • POST: Criar um recurso. • PUT: Atualizar um recurso. • PATH: Atualizar um recurso. • DELETE: Apagar um recurso. Mais comuns:
13. Códigos de retorno Códigos de retorno • 200: OK. • 201: Created. • 204: No Content. • 400: Bad Request. • 401: Unauthorized. • 403: Forbidden. • 404: Not Found. • 405: Method not allowed. • 409: Conflict. • 500: Internal Server Error. Mais comuns:
14. Cabeçalhos Cabeçalhos • Verbo: Tipo da operação (ex. GET) (req). • URI: Identificação do resource (ex. /person) (req). • Content-Type: Formato do corpo (ex. application/json) (req/res). • Authorization: Credenciais (ex. Token foo) (req). • Etag: Hash de identificação de um resource (ex “737060cd8”) (res). • X-: Experimental (ex: x-acme-session) (req/res)
15. Resources Resources • Uma instancia (ou uma coleção) de um objeto (ex: products). • Acessível através de um endpoint (ex: /products/8d2624365). • Suas operações são determinadas através dos verbos (ex: GET /products/). • Podem possuir relacionamentos. • Podem possuir diferentes representações (ex: JSON, YAML, XML).
16. Como Como frameworks frameworks resumem tudo resumem tudo isso? isso?
17. Django Rest Framework
18. Onde está o Onde está o Verbo HTTP ? Verbo HTTP ? Django Rest Framework
19. Onde está o Onde está o Verbo HTTP ? Verbo HTTP ? Onde está o Onde está o Status Code ? Status Code ? Django Rest Framework
20. Onde está o Onde está o Verbo HTTP ? Verbo HTTP ? Onde está o Onde está o Status Code ? Status Code ? O que diabos O que diabos isso faz ? isso faz ? Django Rest Framework
22. Algumas Algumas Boas Práticas Boas Práticas Parar criar uma API que chuta bundas Parar criar uma API que chuta bundas
23. HTTP HTTP • Uso correto dos verbos. • Uso correto dos status code. • Uso correto dos cabeçalhos. Isso é basicamente REST
24. Use Use nomes nomes no Plural no Plural • Procure nomear seus resources no plural: – /products /products, /persons /persons, , /customers /customers • Se preferir o singular, mantenha tudo no singular. • NUNCA misture os dois: – /product /product, /person /person, , /customers /customers
25. Use o Use o verbo verbo no no protocolo, protocolo, não não na na url url • Fuja de urls com verbos: – /getProducts /getProducts, / /createProducts createProducts • Use o verbo no protocolo HTTP: – GET GET /products /products, POST POST /products /products • Seja REST, não RPC. RPC: Remote Procedure Call
26. Deixe a complexidade Deixe a complexidade para a query string para a query string • Filtros, pesquisas e paginação devem ficar na query string: – /products?color=red&type=mobile /products?color=red&type=mobile • Não complique sua base de urls: – /products/redAndMobile /products/redAndMobile
27. Ações devem ser REST Ações devem ser REST • Não quebre padrões para ações: – /machine/{id}/turnOn /machine/{id}/turnOn – /machine/{id}/turnOff /machine/{id}/turnOff • Use os verbos HTTP e deixe explícito que se trata de uma ação: – POST /machine/{id}/action/turn POST /machine/{id}/action/turn (turn on) – DELETE /machine/{id}/action/turn DELETE /machine/{id}/action/turn (turn off) • Se sua API tem muitas ações, talvez você deva usar RPC.
28. Não exponha seus IDs Não exponha seus IDs • Evite ao máximo ids sequenciais: – /persons/1 /persons/1 – /persons/2 /persons/2 • Use UUIDs sempre que possível: – /persons/59988232-29d0-11e5-848c- /persons/59988232-29d0-11e5-848c- 1078d2624365 1078d2624365 – /persons/ /persons/ ??? • Isso é uma questão de segurança.
29. Simplifique Simplifique os os múltiplos múltiplos relacionamentos relacionamentos • Limite as urls a até dois níveis: – /artists/{id}/albums/{id} /artists/{id}/albums/{id} • Se necessário, crie atalhos: – /artists/{id}/albums/{id}/tracks/{id}/... /artists/{id}/albums/{id}/tracks/{id}/... – /albums/{id} /albums/{id} – /tracks/{id} /tracks/{id}
30. Autenticação Autenticação • Não invente o seu próprio sistema maluco de autenticação. • Use um protocolo já conhecido e testado pela comunidade. • De preferencia para o OAuth2, por sua vasta documentação e seus diversos casos de sucesso.
31. Quando você inventa o Quando você inventa o seu próprio sistema de seu próprio sistema de autenticação autenticação
32. É assim que os clientes É assim que os clientes da API reagem da API reagem
33. Erros devem ser Erros devem ser compreensíveis compreensíveis • Respeite os status code HTTP. • Forneça uma descrição do erro para o desenvolvedor. • Forneça uma descrição do erro para o usuário final (caso seja necessário). • Forneça um link para a documentação onde trata do erro ocorrido.
34. Erros devem ser Erros devem ser compreensíveis compreensíveis
35. Erros devem ser Erros devem ser compreensíveis compreensíveis Caso seja mais de um erro, considere retornar uma lista com todos os erros ocorridos no request
36. Considere o cache Considere o cache • Esteja sempre pronto para fazer cache de seus responses. • Os cabeçalhos ETag e If-None-Match podem ser úteis. • NUNCA guarde estado em suas APIs, use o redis ou o memcached para isso.
37. Documentação Documentação • Uma boa API deve possuir uma excelente documentação. • Disponibilize exemplos de consumo da API (de preferência baseados no cURL). curl -X POST -H 'Content-Type: curl -X POST -H 'Content-Type: application/json' -d '{“foo”: “bar”}' application/json' -d '{“foo”: “bar”}' https://fun.com/api/foo https://fun.com/api/foo • Disponibilize um ambiente de sandbox.
38. Muito Muito obrigado! obrigado! drgarcia1986@gmail.com https//twitter.com/drgarcia1986