REST APIs: Como projetar e implementar APIs RESTful
•
5 gostaram•902 visualizações
Este documento fornece uma introdução sobre APIs REST, definindo o que é REST e hipermídia, discutindo como projetar e implementar uma API REST passo a passo e mencionando algumas ferramentas e bibliotecas úteis. O documento explica como entender o fluxo de trabalho da API, construir uma máquina de estados, criar tipos de mídia e implementar a API usando exemplos de pedidos e pagamentos em uma lanchonete.
Recomendados
Recomendados
Mais conteúdo relacionado
Semelhante a REST APIs: Como projetar e implementar APIs RESTful
Semelhante a REST APIs: Como projetar e implementar APIs RESTful (20)
Mais de Guilherme
Mais de Guilherme (20)
REST APIs: Como projetar e implementar APIs RESTful
- 4. Por quê?
- 7. 3º What the f* is Representational State Transfer
- 8. “I am getting frustrated by the number of people calling any HTTP-based interface a REST API.” –Roy Fielding
- 10. Como?
- 11. • Problema conhecido por todos • Passo a passo para projetar e implementar uma API REST • Erros comuns, trade-offs e falácias
- 12. O que é rest e hypermedia?
- 14. O que é REST/Hypermedia? • Construção de sistemas distribuídos • Em 99% dos casos sistemas que funcionam na Web • Aplicativos mobile conversando com APIs • Aplicativos Web convesando com Aplicativos Web • Walledgarden
- 15. O processo 1. Entender o workflow que a API irá implementar 2. Construir máquina de estados 3. Construir media types 4. Implementar :)
- 17. Entender workflow • Pensar em termos de processos de negócio • Quantos e quais passos serão necessários?
- 18. Pagamento Pedido
- 19. O Problema • Ciclo de pedido • Ciclo de pagamento • Independentes • Comunicação assíncrona através de message queue • Maximiza throughput
- 21. Simplificado • Na verdade são 3 ciclos independentes • Mais lucros • Dica: Starbucks Does Not Use Two-Phase Commit
- 22. Criar máquina de estados
- 23. Criar máquina de estados: cliente Pedir Sanduíche preparado Atualizar Pagar Pagamento realizado Pegar Sanduíche entregue
- 26. ( o que é media type? )
- 27. “To some extent, people get REST wrong because I failed to include enough detail on media type design within my dissertation. That’s because I ran out of time […]” –Roy T. Fielding
- 28. Media types • É o que o cliente precisa saber para entender: • Comportamento (ou seja, quais transições saem de ume estado) • Semântica de alguns atributos da representação
- 29. Exemplo: text/html • Ao clicar no <a>: Requisição GET para href • Ao submeter um <form>: Requisição method para action
- 30. Exemplo: text/html • O browser só precisa entender o media type. • Tanto faz se você está vendo o extrato da sua conta do banco ou um verbete na Wikipedia • media type = comportamento + semântica
- 31. Exemplo: APIs • Erros de validação • Internacionalização de mensagens • URLs
- 32. Media types • É por isso que sempre dizem que APIs REST não precisam de Documentação • Você só precisa descrever os media types utilizados • A semântica dos métodos HTTP já é bem definida • Utilizado nos cabeçalhos Accept e Content-‐type
- 36. Sanduíche: Semântica • id • created_at • pao • queijo • status • updated_at
- 37. Pagamento: Semântica • id • created_at • numero_cartao • expira_em • valor
- 38. Semântica • Atributos que tem o mesmo significado para todos os recursos da API • Comportamentos inesperados (erros de validação)
- 39. Comportamento: Relacionamentos { "links": [ { "rel": "self", "href": "/pedidos/1" }, { "rel": "pagamento", "href": "/pagamentos/pedidos/1" } ] }
- 40. Comportamento: Relacionamentos • Representam as transições da nossa máquina de estados • Aumentam o desacoplamento • O cliente não precisa saber URLs a priori
- 41. Mas… Quais métodos utilizar?
- 42. “[…] methods are not given meaning by the media type. Instead, the media type tells the client either what method to use (e.g., anchor implies GET) or how to determine the method to use (e.g., form element says to look in method attribute). The client should already know what the methods mean (they are universal) and how to dereference a URI.” –Roy T. Fielding
- 44. “ Rails is not restful “ Kind of comment…
- 45. Implementar
- 47. Fazer pedido: Requisição POST /pedidos HTTP/1.1 Accept: application/vnd.subway.sanduiche-‐v1+json { "pao": "3queijos", "queijo": "suíço", "recheio": "club" }
- 48. Fazer pedido: Resposta HTTP/1.1 201 Created Content-‐type: application/vnd.subway.sanduiche-‐v1+json { "id": "1", "created_at": "2013-‐10-‐23T05:02Z", "updated_at": null, "pao": "3 queijos", "queijo": "suíço", "recheio": "club", "status": “em preparo", "links": [ { "rel": "self", "href": "/pedidos/1" }, { "rel": "pagamento", "href": "/pagamentos/pedidos/1" } ] }
- 49. Atualizar pedido: Requisição PATCH /pedidos/1 HTTP/1.1 Accept: application/vnd.subway.sanduiche-‐v1+json { "queijo": "cheddar" }
- 50. Atualizar pedido: Resposta HTTP/1.1 200 Ok Content-‐type: application/vnd.subway.sanduiche-‐v1+json { "id": "1", "created_at": "2013-‐10-‐23T05:02Z", "updated_at": null, "pao": "3 queijos", "queijo": "cheddar", "recheio": "club", "links": [ { "rel": "self", "href": "/pedidos/1" }, { "rel": "pagamento", "href": "/pagamentos/pedidos/1" } ] }
- 51. Atualizar pedido: Erro HTTP/1.1 409 Conflict Content-‐type: application/vnd.subway.sanduiche-‐v1+json { "id": "1", "created_at": "2013-‐10-‐23T05:02Z", "updated_at": null, "pao": "3 queijos", "queijo": "suiço", "recheio": "club", "links": [ { "rel": "self", "href": "/pedidos/1" }, { "rel": "pagamento", "href": "/pagamentos/pedidos/1" } ] }
- 52. Como saber se é possível mudar o pedido? OPTIONS /pedidos/1 HTTP/1.1 HTTP/1.1 200 Ok Allow: GET, PATCH
- 53. Pagar pedido: REQUISIÇÃO • Lembra do media type? • Utilizar relacionamentos
- 54. Pagar pedido: REQUISIÇÃO GET /pagamentos/pedidos/1 HTTP/1.1 Accept: application/vnd.subway.sanduiches-‐v1+json { "numero_cartao": "123312", "expira_em": "12/12", "valor": "12.45" }
- 55. Ponto de vista do caixa: fila de sanduíches GET /pedidos HTTP/1.1 Accept: application/vnd.subway.sanduiches-‐v1+json { "total": 12, "page": 1, "per_page": 10, "items": [ { "id": “1”, “status”: "pago" … }, { "id": “2”, “status”, “em preparo" … } ] }
- 56. Listar pedido: media type • É necessário criar seu próprio media type? • Não! Já existem vários: • collection+json • atom+xml
- 57. Gems
- 58. roar beer = Beer.new(:title => "Lonestar Beer") beer.post(order.links[:items])
- 59. jsonapi.org • Media type de propósito geral • Links, Coleções, etc
- 60. Obrigado :)