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.

Transcript

1. REST-fuuuu RESTful e a polícia do HTTP
2. 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
3. RESTful
4. RESTful……who? REpresentational State Transfer -ful: completo, pleno Normalmente (sempre?) baseado em HTTP
5. RESTful……who? Martin Fowler & Leonard Richardson, 2010: Steps toward the glory of REST
6. #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
7. #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> [...]
8. #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’: [ { ...
9. #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’: [ { ...
10. #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!
11. #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’: [ { ...
12. #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’: [ { ...
13. #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
14. #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
15. #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
16. #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
17. #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
18. #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
19. #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’: [ { ...
20. #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’: [ { ...
21. #2: Eu chamo API, tu chamas API... DELETE /api/events/10 ---------------------------------------- HTTP/1.1 204 No Content
22. #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)
23. #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
24. #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)
25. #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
26. #3: HATEOAS Hypermedia As The Engine Of Application State
27. Comofas/ *altamente opinativo!
28. Library recomendada: Restler Classes puras + ORM + Restler = API RESTful e documentada
29. 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)
30. Library recomendada: Restler Classes puras + ORM + Restler = API RESTful e documentada Documentação Código - Word - User Exemplo prático:
31. 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
32. Framework recomendado: Laravel/Lumen Resources automatizados em Controllers + framework
33. Pattern não-recomendado: closures Pattern recomendado para comprar seu ticket para o inferno
34. That’s all, folks! - Richardson’s API Maturity Model - API versioning discussion - HTTP Headers spec - HTTP Verbs - Wikipedia - HTTP Verbs - spec