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

APIs Eficazes com PHP

Db982994346dad910547a7c62a90dadd?s=47 Ravan Scafi
November 24, 2016

APIs Eficazes com PHP

Construir uma API pode parecer fácil. Algumas rotas que retornam conteúdo em JSON, uma forma de autenticação e está pronta. Será mesmo? Uma API eficaz preocupa-se com os desenvolvedores que irão consumi-la. Entenda conceitos como autenticação, autorização, documentação, padronização e negociação de conteúdo. Conheça boas práticas, dicas de segurança, livros, pacotes e recursos úteis.

Essa talk foi apresentada no PHPSP + Talks #1 - Google
https://www.meetup.com/pt-BR/php-sp/events/235641294/

Por favor, avalie a palestra e/ou os slides!
https://joind.in/event/phpsp-talks-1/apis-eficazes-com-php

# Pacotes Relevantes
- Swagger PHP
https://github.com/zircote/swagger-php

- League OAuth2 Server
https://github.com/thephpleague/oauth2-server

- League OAuth2 Client
https://github.com/thephpleague/oauth2-client

- JWT
https://github.com/lcobucci/jwt

- League Fractal
https://github.com/thephpleague/fractal

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

- OAuth 2.0 Specification
https://oauth.net/2/

- JWT.io
https://jwt.io/

- GraphQL
http://graphql.org/

- 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

November 24, 2016
Tweet

More Decks by Ravan Scafi

Other Decks in Technology

Transcript

  1. APIs Eficazes Com PHP

  2. Sobre Mim Ravan Scafi Back-end 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. (ou porque a gente tá aqui hoje) API REST em

    1 Minuto
  6. API REST em 1 minuto Cada recurso tem seu próprio

    URI GET http://meusite.dev/api/users/rscafi
  7. API REST em 1 minuto Verbos HTTP indicam a ação

    GET http://meusite.dev/api/users/rscafi
  8. API REST em 1 minuto Diferenciação por IDs GET http://meusite.dev/api/users/rscafi

  9. Motivação Por que fazer uma API? E o que isto

    implica?
  10. Documentação Como e por que documentar uma API?

  11. “ apiary.io “Uma API é apenas tão boa quanto sua

    documentação”
  12. None
  13. Swagger / Open API Initiative Uma forma de documentar sua

    API
  14. Swagger / Open API Initiative Único arquivo swagger.json (ou .yml)

  15. Swagger / Open API Initiative Consumível por humanos e máquinas

  16. { "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) (...)", "version": "1.0.0", "title": "Swagger Petstore", "termsOfService": "http://swagger.io/terms/", "contact": { "email": "apiteam@swagger.io" },
  17. "paths": { "/pet": { "post": { "tags": [ "pet" ],

    "summary": "Add a new pet to the store", "description": "", "operationId": "addPet", "consumes": [ "application/json", "application/xml"
  18. "parameters": [ { "in": "body", "name": "body", "description": "Pet object

    that needs to (...)", "required": true, "schema": { "$ref": "#/definitions/Pet" } } ], "responses": { "405": { "description": "Invalid input"
  19. None
  20. Documentação Mantenha próxima ao código

  21. Documentação Revisite periodicamente

  22. Documentação Se possível, faça Documentation-First

  23. None
  24. /** * @SWG\Info(title="My First API", version="0.1") */ /** * @SWG\Get(

    * path="/api/resource.json", * @SWG\Response(response="200", description="An example resource") * ) */
  25. Empatia é a chave

  26. 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.
  27. Design O que me atentar ao fazer uma API?

  28. Versionamento Somente exponha a “versão cheia” (v1, v2)

  29. Versionamento Evite ao máximo Breaking Changes

  30. 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
  31. Proteja-se com Mutators Representam Recursos da API

  32. Proteja-se com Mutators Criam uma barreira entre seus Models e

    sua API
  33. Auxiliam em Typecasting e Relacionamentos Proteja-se com Mutators

  34. <?php namespace Api\V1\Transformers\User; use Api\V1\Transformers\TranformerInterface; use DateTime; class UserTransformer implements

    TranformerInterface { public function transform(User $user) { return [ 'name' => "{$user->firstName} {$user->lastName}", 'email' => $user->getEmail(), 'birthday' => $user->birthday->format(DateTime::RFC3339), ]; } }
  35. <?php namespace Api\V1\Transformers\User; use Api\V1\Transformers\TranformerInterface; use DateTime; class UserTransformer implements

    TranformerInterface { public function transform(User $user) { return [ 'name' => "{$user->firstName} {$user->lastName}", 'email' => $user->getEmail(), 'birthday' => $user->birthday->format(DateTime::RFC3339), ]; } }
  36. <?php namespace Api\V1\Transformers\User; use Api\V1\Transformers\TranformerInterface; use DateTime; class UserTransformer implements

    TranformerInterface { public function transform(User $user) { return [ 'name' => "{$user->firstName} {$user->lastName}", 'email' => $user->getEmail(), 'birthday' => $user->birthday->format(DateTime::RFC3339), ]; } }
  37. <?php namespace Api\V1\Transformers\User; use Api\V1\Transformers\TranformerInterface; use DateTime; class UserTransformer implements

    TranformerInterface { public function transform(User $user) { return [ 'name' => "{$user->firstName} {$user->lastName}", 'email' => $user->getEmail(), 'birthday' => $user->birthday->format(DateTime::RFC3339), ]; } }
  38. <?php namespace Api\V1\Transformers\User; use Api\V1\Transformers\TranformerInterface; use DateTime; class UserTransformer implements

    TranformerInterface { public function transform(User $user) { return [ 'name' => "{$user->firstName} {$user->lastName}", 'email' => $user->getEmail(), 'birthday' => $user->birthday->format(DateTime::RFC3339), ]; } }
  39. <?php namespace Api\V1\Transformers\User; use Api\V1\Transformers\TranformerInterface; use DateTime; class UserTransformer implements

    TranformerInterface { public function transform(User $user) { return [ 'name' => "{$user->firstName} {$user->lastName}", 'email' => $user->getEmail(), 'birthday' => $user->birthday->format(DateTime::RFC3339), ]; } }
  40. Negociação de Conteúdo Como ter uma comunicação eficiente com os

    usuários?
  41. JSON, XML, CSV? Negociação de Conteúdo

  42. Trazer Relacionamentos e Recursos Embeddados? Negociação de Conteúdo

  43. Metadados: URI, página atual, contagem total Negociação de Conteúdo

  44. Use cabeçalhos HTTP quando relevante Negociação de Conteúdo

  45. Respostas Como passar as informações corretas aos usuários?

  46. Padronize códigos HTTP de resposta Respostas

  47. Padronize campos de datas, floats, moedas Respostas

  48. Padronize Metadados Respostas

  49. Não reinvente a roda Respostas

  50. { "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" }
  51. { "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 }
  52. { "errorCode": 500, "errors": [ "Unknown error occurred. Check you

    input or try again later." ] } Nunca exponha Exceções para o Usuário { "exception": “NullPointerException” }
  53. Autorização e Autenticação Como identificar meus usuários e suas permissões?

  54. Autorização e Autenticação Qual a diferença?

  55. Autorização Baseada em Sessão: NÃO

  56. Autorização APIs devem ser sem estados (stateless)

  57. Autorização Implementação em Mobile pode ser custosa

  58. Autorização Baseada em Tokens: SIM

  59. Segurança Como proteger minha API?

  60. Segurança Evite expor IDs sequenciais (use HashIDs por exemplo)

  61. Segurança Limite requisições, de forma configurável (throttling)

  62. Segurança Não utilize logins por senha (exceto em apps próprios)

  63. Segurança API somente em HTTPS

  64. Dicas e Recursos Onde ir a seguir?

  65. OAuth 2.0 Fluxos de Autorização

  66. JWT Tokens de Autenticação

  67. GraphQL Negociação de Conteúdo e Documentação! (substitui o REST)

  68. • Build APIs You Won’t Hate • HTTP API Design

    Guide • Open API Initiative • Petstore (Swagger UI) • 2 Legged OAuth • API Evangelist Leituras
  69. • Slack APIs You Won’t Hate • ngrok • Apigee

    • Postman • Paw Dicas
  70. Empatia é a chave

  71. Obrigado! @ravanscafi https://joind.in/talk/913dd

  72. Estamos Contratando! Dev BackEnd, Dev FrontEnd rscafi@leroymerlin.com.br

  73. Agradecimentos Agradecimentos especiais a todos do SlidesCarnival que fizeram e

    disponibilizaram o template da apresentação gratuitamente. Ao PHPSP pelo convite e organização do evento <3