Upgrade to PRO for Only $50/Year—Limited-Time Offer! 🔥

APIs do Jeito Certo

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/

Ravan Scafi

September 17, 2016
Tweet

More Decks by Ravan Scafi

Other Decks in Programming

Transcript

  1. Sobre Mim Ravan Scafi Backend Developer na Leroy Merlin Brasil

    Co-organizador do Meetup do Laravel SP @ravanscafi
  2. 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.
  3. 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
  4. 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
  5. { "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": "[email protected]" }, "license": {
  6. "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"
  7. "schemes": [ "http" ], "paths": { "/pet": { "post": {

    "tags": [ "pet" ], "summary": "Add a new pet to the store", "description": "", "operationId": "addPet", "consumes": [ "application/json", "application/xml"
  8. "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",
  9. "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"
  10. "responses": { "405": { "description": "Invalid input" } }, "security":

    [ { "petstore_auth": [ "write:pets", "read:pets" ] } ] },
  11. Documentação: Dicas • Mantenha a documentação próxima ao código •

    DRY • Revisite a documentação • Se possível, faça Documentation-First
  12. 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.
  13. 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
  14. Proteja-se com Mutators • Representam Recursos da API • Criam

    uma barreira entre seus Models e sua API • Typecasting e Relacionamentos
  15. <?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'), ]; } }
  16. 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
  17. Respostas • Padronize campos de datas, floats, moedas • Padronize

    códigos HTTP de resposta • Padronize metadados, paginação, etc. • Não reinvente a roda
  18. { "data": { "name": "John Doe", "email": "[email protected]", "birthday": "17/09/2016"

    } } Faça um “wrap” da resposta { "name": "John Doe", "email": "[email protected]", "birthday": "17/09/2016" }
  19. { "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 }
  20. { "errorCode": 451942, "errors": [ "Username must contain only letters

    and numbers", "E-mail is required" ] } Nunca exponha Exceções para o Usuário { "exception": “NullPointerException” }
  21. 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?
  22. 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
  23. 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 )
  24. 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)
  25. • Build APIs You Won’t Hate • HTTP API Design

    Guide • Open API Initiative • Petstore (Swagger UI) • 2 Legged OAuth • API Evangelist Leituras
  26. Agradecimentos Agradecimentos especiais a todos do SlidesCarnival que fizeram e

    disponibilizaram o template da apresentação gratuitamente.