REST-fuuuu
1 gostou545 visualizações
O documento discute os princípios do REST e como implementá-lo corretamente usando HTTP. Primeiro, descreve vários estágios de maturidade de APIs, desde o uso inadequado de XML/JSON e verbos HTTP até a implementação completa do REST. Em seguida, explica como usar corretamente recursos, verbos HTTP, códigos de status e demais princípios do REST. Por fim, recomenda ferramentas como Restler e Laravel para desenvolver APIs RESTful de forma fácil e robusta.
![#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>
[...]](https://image.slidesharecdn.com/rest-fuuuu-151028020420-lva1-app6892/85/REST-fuuuu-7-320.jpg)
![#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’: [
{
...](https://image.slidesharecdn.com/rest-fuuuu-151028020420-lva1-app6892/85/REST-fuuuu-8-320.jpg)
![#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’: [
{
...](https://image.slidesharecdn.com/rest-fuuuu-151028020420-lva1-app6892/85/REST-fuuuu-9-320.jpg)
![#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’: [
{
...](https://image.slidesharecdn.com/rest-fuuuu-151028020420-lva1-app6892/85/REST-fuuuu-11-320.jpg)
![#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’: [
{
...](https://image.slidesharecdn.com/rest-fuuuu-151028020420-lva1-app6892/85/REST-fuuuu-12-320.jpg)
![#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’: [
{
...](https://image.slidesharecdn.com/rest-fuuuu-151028020420-lva1-app6892/85/REST-fuuuu-19-320.jpg)
![#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’: [
{
...](https://image.slidesharecdn.com/rest-fuuuu-151028020420-lva1-app6892/85/REST-fuuuu-20-320.jpg)
REST-fuuuu
- 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
- 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