APIs do Jeito Certo

Construir uma API pode parecer fácil. Algumas rotas que retornam conteúdo em JSON, uma forma de autenticação e pronto. Será mesmo?

Uma API feita do jeito certo preocupa-se com os desenvolvedores que irão consumí-la. Autenticação, Autorização, Documentação, Padronização, Negociação de Conteúdo. Boas práticas, dicas de segurança, livros e recursos úteis. Várias lições aprendidas ao se montar uma API pública para outros desenvolvedores.

Essa talk foi apresentada no #1 ABCDev - 2016
http://2016.abcdevelopers.org/

# Links da Apresentação
- Tweet sobre a API da UPS
https://twitter.com/danharper7/status/748550285761601536

- Livro Build APIs You Won’t Hate do Phil Sturgeon
https://leanpub.com/build-apis-you-wont-hate

- HTTP API Design Guide
https://github.com/interagent/http-api-design

- Open API Initiative
https://openapis.org/

- Petstore (Swagger UI)
http://petstore.swagger.io/

- 2 Legged OAuth
http://stackoverflow.com/questions/14250383/how-does-2-legged-oauth-work-in-oauth-2-0

- API Evangelist
http://apievangelist.com/

- Slack APIs You Won’t Hate
https://slack.apisyouwonthate.com/

- ngrok
https://ngrok.com/

- Apigee
http://apigee.com/about/

- Postman
https://www.getpostman.com/

- Paw
https://paw.cloud/

Agradecimento ao Slides Carnival
http://www.slidescarnival.com/

Transcript

1. APIs do Jeito Certo
2. Sobre Mim Ravan Scafi Backend Developer na Leroy Merlin Brasil Co-organizador do Meetup do Laravel SP @ravanscafi
3. API? O que é uma API?
4. Interface é um elemento que proporciona uma ligação física ou lógica entre dois sistemas ou partes de um sistema que não poderiam ser conectados diretamente.
5. API REST em 1 minuto • Cada recurso tem seu próprio URI • Verbos HTTP indicam a ação • Sem estado! GET http://meusite.dev/api/users/rscafi
6. Motivação Por que fazer uma API? E o que isto implica?
7. Documentação Como documentar uma API?
8. “ apiary.io “Uma API é apenas tão boa quanto sua documentação”
10. Swagger / Open API Initiative • Uma forma de documentar sua API • Único arquivo swagger.json • Consumível por humanos e máquinas • Swagger UI e ReDoc
11. { "swagger": "2.0", "info": { "description": "This is a sample server Petstore server. You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). For this sample, you can use the api key `special-key` to test the authorization filters.", "version": "1.0.0", "title": "Swagger Petstore", "termsOfService": "http://swagger.io/terms/", "contact": { "email": "apiteam@swagger.io" }, "license": {
12. "license": { "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0.html" } }, "host": "petstore.swagger.io", "basePath": "/v2", "tags": [ { "name": "pet", "description": "Everything about your Pets", "externalDocs": { "description": "Find out more", "url": "http://swagger.io"
13. "schemes": [ "http" ], "paths": { "/pet": { "post": { "tags": [ "pet" ], "summary": "Add a new pet to the store", "description": "", "operationId": "addPet", "consumes": [ "application/json", "application/xml"
14. "summary": "Add a new pet to the store", "description": "", "operationId": "addPet", "consumes": [ "application/json", "application/xml" ], "produces": [ "application/xml", "application/json" ], "parameters": [ { "in": "body", "name": "body",
15. "parameters": [ { "in": "body", "name": "body", "description": "Pet object that needs to be added to the store", "required": true, "schema": { "$ref": "#/definitions/Pet" } } ], "responses": { "405": { "description": "Invalid input"
16. "responses": { "405": { "description": "Invalid input" } }, "security": [ { "petstore_auth": [ "write:pets", "read:pets" ] } ] },
19. Documentação: Dicas • Mantenha a documentação próxima ao código • DRY • Revisite a documentação • Se possível, faça Documentation-First
20. Empatia é a chave
21. Empatia é a capacidade de se identificar com outra pessoa, de sentir o que ela sente, de querer o que ela quer, de apreender do modo como ela apreende etc.
22. Design O que me atentar ao fazer uma API?
23. Versionamento • Somente exponha a “versão cheia” (v1, v2) • Evite ao máximo Breaking Changes
24. NÃO • Adicionar campos • Adicionar recursos • Adicionar endpoints • Corrigir bugs * O que causa uma Breaking Change? SIM • Remover campos • Renomear campos • Remover recursos • Remover endpoints
25. Proteja-se com Mutators • Representam Recursos da API • Criam uma barreira entre seus Models e sua API • Typecasting e Relacionamentos
26. <?php namespace App\User; use Api\V1\TranformerInterface; class UserTransformer implements TranformerInterface { public function transform(User $user) { return [ 'name' => $user->firstName . ' ' . $user->lastName, 'email' => $user->getEmail(), 'birthday' => $user->birthday->format('d/m/Y'), ]; } }
27. Negociação de Conteúdo Como ter uma comunicação eficiente com os usuários?
28. Negociação de Conteúdo • JSON, XML, CSV? ◦ Lembre-se: JSON é JavaScript (use camelCase) • Relacionamentos / Recursos Embeddados: trazer ou não? • Metadados: URI, página atual, contagem total • Use cabeçalhos HTTP quando relevante • Verbo HTTP: override com _method
29. Respostas Como passar as informações corretas aos usuários?
30. Respostas • Padronize campos de datas, floats, moedas • Padronize códigos HTTP de resposta • Padronize metadados, paginação, etc. • Não reinvente a roda
31. { "data": { "name": "John Doe", "email": "johndoe@gmail.com", "birthday": "17/09/2016" } } Faça um “wrap” da resposta { "name": "John Doe", "email": "johndoe@gmail.com", "birthday": "17/09/2016" }
32. { "errorCode": 451942, "errors": [ "Username must contain only letters and numbers", "E-mail is required" ] } Mostre a descrição do erro, não somente um código { "error": 451942 }
33. { "errorCode": 451942, "errors": [ "Username must contain only letters and numbers", "E-mail is required" ] } Nunca exponha Exceções para o Usuário { "exception": “NullPointerException” }
34. Autorização e Autenticação Como identificar meus usuários e suas permissões?
35. Autenticação • Baseados em Sessão: NÃO ◦ APIs devem ser sem estados (stateless) ◦ Implementação em Mobile é custosa • Baseados em Token: SIM • OAuth? OAuth2? JWT? Http-Basic?
36. OAuth vs JWT • Não são “concorrentes” diretos • É possível utilizar os dois em conjunto • OAuth: concebido para autorização (pseudo autenticação) ◦ 3-legged vs 2-legged • JWT: Concebido para Claims / Autenticação
37. Como se parece um JWT? Codificado eyJhbGciOiJIUzI1NiIsInR5cCI6IkpX VCJ9.eyJzdWIiOiIxMjM0NTY3ODkw IiwibmFtZSI6IkpvaG4gRG9lIiwiYW RtaW4iOnRydWV9.TJVA95OrM7E2 cBab30RMHrHDcEfxjoYZgeFONFh 7HgQ Decodificado Header: { "alg": "HS256", "typ": "JWT" } Payload: { "sub": "1234567890", "name": "John Doe", "admin": true } Verify signature: HMACSHA256( base64UrlEncode(header) + "." + base64UrlEncode(payload), c2VjcmV0 )
38. Segurança Como proteger minha API?
39. Segurança • Evite expor IDs sequenciais (HashIDs por exemplo) • Limite as requisições (throttling) de forma configurável • Não utilize logins por senha (exceto em apps próprios) • API somente em HTTPS • Responda rápido a vulnerabilidades (0-days, etc)
40. Dicas e Recursos Onde ir a seguir?
41. • Build APIs You Won’t Hate • HTTP API Design Guide • Open API Initiative • Petstore (Swagger UI) • 2 Legged OAuth • API Evangelist Leituras
42. • Slack APIs You Won’t Hate • ngrok • Apigee • Postman • Paw Dicas
43. Empatia é a chave
44. Obrigado! @ravanscafi hello@ravan.me
45. Estamos Contratando! Dev BackEnd, Dev FrontEnd, UX rscafi@leroymerlin.com.br
46. Agradecimentos Agradecimentos especiais a todos do SlidesCarnival que fizeram e disponibilizaram o template da apresentação gratuitamente.