Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

REST-fuuuu - Boas práticas RESTful [PHPeste 2017]

2,028 views

Published on

Uma palestra de boas práticas para APIs RESTful, apresentando os principais conceitos e sugerindo algumas ferramentas para o desenvolvimento e úteis no dia-a-dia.

Para ver os slides comentados, acesse https://docs.google.com/presentation/d/1ouKB72zKIu0IxSbk58-h0JxjD_tESW76lmFgMzF7OJo/edit?usp=sharing

Published in: Technology
  • Be the first to comment

REST-fuuuu - Boas práticas RESTful [PHPeste 2017]

  1. 1. REST-fuuuu RESTful e a polícia do HTTP
  2. 2. Igor Santos who? - Desenvolvedor PHP desde os 16 (~10 anos) - Trabalho com APIs REST: ~4 anos - Desenvolvedor React: ~2 ano - Já mexi com Ruby, mas... - Já brinquei com C e Python mas… - Já me diverti com Ember mas… Atualmente, sou Freelancer remoto Full-stack na Join the network! Talk to me :D
  3. 3. Remoto. MESMO.
  4. 4. RESTful
  5. 5. RESTful……who? REpresentational State Transfer -ful: completo, pleno Normalmente (sempre?) baseado em HTTP(S)
  6. 6. RESTful……who? Martin Fowler & Leonard Richardson, 2010: Steps toward the glory of REST
  7. 7. RESTful……who? Martin Fowler & Leonard Richardson, 2010: Steps toward the glory of REST Zoeira REST de verdade
  8. 8. #0: O pântano do POX* ✓ Comunicação sobre o HTTP ✗ HTTP = protocolo facilitador de rede, somente ✗ Verbos HTTP? GETPOST all the things! *POX: Plain Old XML
  9. 9. #0: O pântano do POX* *POX: Plain Old XML
  10. 10. #0: O pântano do POX* *POX: Plain Old XML POST /api/ <listEvents date="2016-10-22"/> ---------------------------------------- HTTP/1.1 200 OK <eventsList> <event id="10"> <dates begin="2016-10-22"> <topics> <topic>HTTP</topic> <topic>REST</topic> </topics> [...]
  11. 11. #0: O pântano do POJ* *POJ: Pure and Old JSON POST /api/?method=events.list { date: "2015-10-22" } ---------------------------------------- HTTP/1.1 200 OK [ { "id": 10, "start": "2015-10-22", "topics": [ "PHP", "REST" ], "speakers": [ { ...
  12. 12. #1: Resources! ✓ Comunicação sobre o HTTP ✓ URIs indicam o recurso desejado ✓ Recursos HTTP simplificados, para dividir os requests ✗ Verbos HTTP? GETPOST all the things! AKA entidades
  13. 13. #1: Resources RPC! POST /api/events { "method": "list", date: "2015-10-22" } ---------------------------------------- HTTP/1.1 200 OK [ { "id": 10, "start": "2015-10-22", "topics": [ "HTTP", "REST" ], "speakers": [ { ...
  14. 14. #1: Resources RPC! POST /api/events/search { date: "2015-10-22" } ---------------------------------------- HTTP/1.1 200 OK [ { "id": 10, "start": "2015-10-22", "topics": [ "PHP", "REST" ], "speakers": [ { ...
  15. 15. #2: Eu chamo API, tu chamas API... ✓ Comunicação sobre o HTTP ✓ URIs indicam o recurso desejado ✓ Recursos HTTP dividem os requests ✓ Verbos HTTP dividem as operações
  16. 16. #2: Eu chamo API, tu chamas API... Subníveis de uso dos Verbos HTTP GET POST PUT DELETE Básico Consultas Criação Edição Remoção X X POST /clientes/buscar GET /clientes
  17. 17. #2: Eu chamo API, tu chamas API... Subníveis de uso dos Verbos HTTP GET POST PUT DELETE Básico Consultas Criação Edição Remoção X X Quase lá Consultas Criação Edição X Remoção POST /clientes/apagar/2 DELETE /clientes/2
  18. 18. #2: Eu chamo API, tu chamas API... Subníveis de uso dos Verbos HTTP GET POST PUT DELETE Básico Consultas Criação Edição Remoção X X Quase lá Consultas Criação Edição X Remoção RESTful-ish Consultas Criação Edição Remoção POST /clientes/edit/27 PUT /clientes/27
  19. 19. #2: Eu chamo API, tu chamas API... Subníveis de uso dos Verbos HTTP GET POST PUT DELETE PATCH Básico Consultas Criação Edição Remoção X X X Quase lá Consultas Criação Edição X Remoção X RESTful-ish Consultas Criação Edição Remoção X RESTful-ish bônus Consultas Criação Edição Remoção Edição parcial
  20. 20. #2: Eu chamo API, tu chamas API... Subníveis de uso dos Verbos HTTP GET POST PUT DELETE PATCH Básico Consultas Criação Edição Remoção X X X Quase lá Consultas Criação Edição X Remoção X RESTful-ish Consultas Criação Edição Remoção X RESTful-ish bônus Consultas Criação Edição Remoção Edição parcial RESTful-ish bônus plus Além dos verbos certos, usa os códigos HTTP e headers corretos
  21. 21. #2: Eu chamo API, tu chamas API... GET /api/events?date=2016-10-22 ---------------------------------------- HTTP/1.1 200 OK [ { "id": 10, "start": "2016-10-22", "topics": [ "HTTP", "REST" ], "speakers": [ { ...
  22. 22. #2: Eu chamo API, tu chamas API... POST /api/events { "start": "2016-10-22", ... } ---------------------------------------- HTTP/1.1 201 Created [ { "id": 10, "start": "2016-10-22", "topics": [ "HTTP", "REST" ], "speakers": [ { ...
  23. 23. #2: Eu chamo API, tu chamas API... DELETE /api/events/10 ---------------------------------------- HTTP/1.1 204 No Content
  24. 24. #2.5: RESTful-ish 1. Códigos HTTP - 200: OK, tá aqui o que você pediu - 201: Criei, olha aqui o que eu fiz - 204: Funcionou, mas não tenho mais nada pra te dizer - 400: erro genérico do usuário - 401: OW, quem é você? - 403: OW, sei quem é você mas isso aqui não é pro teu bico - 404: tem nada disso aqui não - 405: verbo incorreto - 406: não consigo gerar no formato que você quer - 422: sabe nem escreve direito, mano - 500: CORRÃO PARA AS MONTANHAS - 501: não sei fazer isso não
  25. 25. Árvore de decisão de códigos HTTP
  26. 26. #2.5: RESTful-ish Stateless, formats, versioning...
  27. 27. #2.5: RESTful-ish 2. Stateful - HTTP = stateless - Stateless <> sessão
  28. 28. #2.5: RESTful-ish 2. Stateful - HTTP = stateless - Stateless <> sessão - API <3 sessão - API + HTTP + sessão = - HTTP Auth: autentica o usuário inicialmente - HTTP Cookie - re-identifica o usuário, tornando desnecessário re-autenticar a cada novo request
  29. 29. #2.5: RESTful-ish 2. Stateful - HTTP = stateless - Stateless <> sessão - API <3 sessão - API + HTTP + sessão = - HTTP Cookie: inseguro no geral - HTTP Auth: autentica o usuário inicialmente - JSON Web Token: mantém o estado do lado do cliente de modo seguro, livrando o servidor disso
  30. 30. #2.5: RESTful-ish 3. Formatos de resposta - Método A: header HTTP Accept: text/xml - Método B: extensão na URI: /events.json - O correto: aceitar os dois métodos, e responder em XML e JSON - O mais comum: um dos dois métodos - ou nenhum, e responder em JSON (mais leve de implementar e interpretar)
  31. 31. #2.5: RESTful-ish 4. Versionamento da API - Método A: incluído na URL - Método B: header HTTP customizado - Método C: incluído no header Accept - O correto: nenhum - O mais comum: na URL - mais fácil de implementar dos dois lados e associa diretamente o método, o resource e a resposta à disponibilidade destes na API
  32. 32. #2.5: RESTful-ish 4. Versionamento da API - Método A: incluído na URL - Método B: header HTTP customizado - Método C: incluído no header Accept - O correto: nenhum - O mais comum: na URL - mais fácil de implementar dos dois lados e associa diretamente o método, o resource e a resposta à disponibilidade destes na API
  33. 33. #3: HATEOAS Hypermedia As The Engine Of Application State
  34. 34. #3: HATEOAS Links definem como se mover dentro da API. Em teoria, permitiria aplicações automatizadas, consumidoras de APIs.
  35. 35. #3: HATEOAS Links definem como se mover dentro da API. Na prática, pode ser usado para automatizar certas atividades numa aplicação.
  36. 36. #3: HATEOAS JSON API Spec - Uma especificação de verdade para APIs!
  37. 37. #3: HATEOAS JSON API Spec - Uma especificação de verdade para APIs! - Bem completa, complexa mas bem poderosa - Dá pra fazer um monte de coisas com ela - Muito legal <3
  38. 38. #3: HATEOAS JSON API Spec - Uma especificação de verdade para APIs! - Bem completa, complexa mas bem poderosa - Paginação e navegação entre recursos - Requisição de recursos relacionados no mesmo payload - Meta informações sobre o request - Formato definido entre requests de uma única ou múltiplas entradas, dados de identificação e atributos, relacionamentos, etc
  39. 39. Comofas/ *altamente opinativo!
  40. 40. Library recomendada: Restler Classes puras + ORM + Restler = API RESTful e documentada OUTDATED
  41. 41. Library recomendada: Restler Classes puras + ORM + Restler = API RESTful e documentada - Curva de aprendizado ≅ 0 - Muito leve; configuração flexível e customizável - Features baseadas nas próprias features do OO e PHPDoc (assim como o REST é baseado no HTTP, ahá!), como validação, documentação, rotas customizadas, códigos de retorno, etc - Suporta Rate limiting e OAuth 2 - Suporta respostas em JSON, XML, YAML, Plist e Amf - Documentação automática e muito boa (Swagger) OUTDATED
  42. 42. Library recomendada: Restler Classes puras + ORM + Restler = API RESTful e documentada Documentação Código - Word - User Exemplo prático: OUTDATED
  43. 43. Framework recomendado: Laravel/Lumen Resources automatizados em Controllers + framework - Frameworks simplificados, e componentizados - Bem leve - Configuração flexível e customizável - ORM poderoso já embutido - Diversas outras ferramentas integradas, como queues, events, logs, encriptação, validação, etc
  44. 44. Framework recomendado: Laravel/Lumen Resources automatizados em Controllers + framework
  45. 45. Pattern não-recomendado: closures
  46. 46. Pattern não-recomendado: closures Pattern recomendado para comprar seu ticket para o inferno
  47. 47. Testes? Quer avaliar se a API tá funcionando como devia? Postman for the rescue! Ou Apiary .
  48. 48. Se perdeu? Tá faltando documentação? Swagger, API Blueprint, Apiary, RAML, Postman, etc.
  49. 49. Learn more about the opportunities, come talk to me :) Do you speak English? Do you feel you’re great at what you do? Looking for good clients, great pay, awesome teams and freedom?
  50. 50. That’s all, folks! - Richardson’s API Maturity Model - API versioning discussion - HTTP Headers spec - HTTP Verbs: Wikipedia / Spec - JSON API spec - Postman - Toptal Engineering Blog *.com/igorsantos07 *.com/igorsantos07 *.com/in/igorsantos07 Portfolio: freelancer.igorsantos.com.br Apply: toptal.igorsantos.com.br
  51. 51. That’s all, folks! Peço desculpas por todas as piadas e trocadilhos ruins usados nesta palestra. Carlos Alberto de Nóbrega não esteve envolvido com a mesma. *.com/igorsantos07 *.com/igorsantos07 *.com/in/igorsantos07 Portfolio: freelancer.igorsantos.com.br Apply: toptal.igorsantos.com.br

×