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

REST-fuuuu

 REST-fuuuu

A base de boas práticas para APIs RESTful. Explico os conceitos básicos do modelo de maturidade REST e indico algumas ferramentas para criação de servidores REST em PHP.

Avatar for Igor Santos

Igor Santos

October 24, 2015
Tweet

More Decks by Igor Santos

Other Decks in Technology

Transcript

  1. Igor Santos who? - Desenvolvedor PHP desde os 16 (~7

    anos) - Já mexi com Ruby mas larguei essa vida - Já brinquei com C e Python mas… too much - Já mexi com JS e Titanium Mobile mas não dá sustento - Já me diverti com Ember mas… deixa pra lá - Já mexi com REST, tanto no servidor e cliente, e sempre que posso, volto pra área - Sempre no PHP, e esbarrando no JS
  2. #0: O pântano do POX* ✓ Comunicação sobre o HTTP

    ✗ HTTP = protocolo facilitador de rede, somente ✗ Recursos? é de comer? RPC FTW ✗ Verbos HTTP? GETPOST all the things! *POX: Plain Old XML
  3. #0: O pântano do POX* *POX: Plain Old XML POST

    /api/ <listEvents date=”2015-10-22”/> ---------------------------------------- HTTP/1.1 200 OK <eventsList> <event id=”10”> <dates begin=”2015-10-22”> <topics> <topic>PHP</topic> <topic>REST</topic> </topics> [...]
  4. #0: O pântano do POJ-RPC* *POJ-RPC: Plain Old JSON over

    RPC POST /api/ { ‘method’: ‘listEvents’, date: ‘2015-10-22’ } ---------------------------------------- HTTP/1.1 200 OK [ { ‘id’: 10, ‘start’: ‘2015-10-22’, ‘topics’: [ ‘PHP’, ‘REST’ ], ‘speakers’: [ { ...
  5. #0: O pântano do POJ* *POJ: Plain 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’: [ { ...
  6. #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!
  7. #1: Resources RPC! POST /api/events { ‘method’: ‘list’, date: ‘2015-10-22’

    } ---------------------------------------- HTTP/1.1 200 OK [ { ‘id’: 10, ‘start’: ‘2015-10-22’, ‘topics’: [ ‘PHP’, ‘REST’ ], ‘speakers’: [ { ...
  8. #1: Resources RPC! POST /api/events/list { date: ‘2015-10-22’ } ----------------------------------------

    HTTP/1.1 200 OK [ { ‘id’: 10, ‘start’: ‘2015-10-22’, ‘topics’: [ ‘PHP’, ‘REST’ ], ‘speakers’: [ { ...
  9. #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
  10. #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
  11. #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
  12. #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
  13. #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
  14. #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
  15. #2: Eu chamo API, tu chamas API... GET /api/events?date=2015-10-22 ----------------------------------------

    HTTP/1.1 200 OK [ { ‘id’: 10, ‘start’: ‘2015-10-22’, ‘topics’: [ ‘PHP’, ‘REST’ ], ‘speakers’: [ { ...
  16. #2: Eu chamo API, tu chamas API... POST /api/events {

    ‘start’: ‘2015-10-22’, [...] } ---------------------------------------- HTTP/1.1 201 Created [ { ‘id’: 10, ‘start’: ‘2015-10-22’, ‘topics’: [ ‘PHP’, ‘REST’ ], ‘speakers’: [ { ...
  17. #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 formado que você quer - 500: CORRÃO PARA AS MONTANHAS - 501: não sei fazer isso não - 503: deu treta com a API que eu uso (API, BD, etc)
  18. #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
  19. #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, e responder em JSON (mais leve de implementar e interpretar)
  20. #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
  21. 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)
  22. Library recomendada: Restler Classes puras + ORM + Restler =

    API RESTful e documentada Documentação Código - Word - User Exemplo prático:
  23. 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 - Já esbarrei em alguns bugs feiosos
  24. That’s all, folks! - Richardson’s API Maturity Model - API

    versioning discussion - HTTP Headers spec - HTTP Verbs - Wikipedia - HTTP Verbs - spec