Upgrade to Pro — share decks privately, control downloads, hide ads and more …

APIs do Jeito Certo

Db982994346dad910547a7c62a90dadd?s=47 Ravan Scafi
September 17, 2016

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/

Db982994346dad910547a7c62a90dadd?s=128

Ravan Scafi

September 17, 2016
Tweet

More Decks by Ravan Scafi

Other Decks in Programming

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”
  9. None
  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" ] } ] },
  17. None
  18. None
  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.