REST-fuuuu

RESTful e a polícia do HTTP

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

RESTful

RESTful……who?

REpresentational

State

Transfer

-ful: completo, pleno

Normalmente (sempre?) baseado em HTTP

RESTful……who?

Martin Fowler & Leonard Richardson, 2010: Steps toward the glory of REST

#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

#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>[...]

#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’: [

{...

#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’: [

{...

#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!

#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’: [

{...

#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’: [

{...

#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

#2: Eu chamo API, tu chamas API... Subníveis de uso dos Verbos HTTP

GET POST PUT DELETE

Básico ConsultasCriaçãoEdição

RemoçãoX X

#2: Eu chamo API, tu chamas API... Subníveis de uso dos Verbos HTTP

GET POST PUT DELETE

Básico ConsultasCriaçãoEdição

RemoçãoX X

Quase lá Consultas CriaçãoEdição X Remoção

#2: Eu chamo API, tu chamas API... Subníveis de uso dos Verbos HTTP

GET POST PUT DELETE

Básico ConsultasCriaçãoEdição

RemoçãoX X

Quase lá Consultas CriaçãoEdição X Remoção

RESTful-ish Consultas Criação Edição Remoção

#2: Eu chamo API, tu chamas API... Subníveis de uso dos Verbos HTTP

GET POST PUT DELETE PATCH

Básico ConsultasCriaçãoEdição

RemoçãoX X X

Quase lá Consultas CriaçãoEdição X Remoção X

RESTful-ish Consultas Criação Edição Remoção X

RESTful-ishbônus

Consultas Criação Edição Remoção Edição parcial

#2: Eu chamo API, tu chamas API... Subníveis de uso dos Verbos HTTP

GET POST PUT DELETE PATCH

Básico ConsultasCriaçãoEdição

RemoçãoX X X

Quase lá Consultas CriaçãoEdição X Remoção X

RESTful-ish Consultas Criação Edição Remoção X

RESTful-ishbônus

Consultas Criação Edição Remoção Edição parcial

RESTful-ishbônus plus

Além dos verbos certos,usa os códigos HTTP e headers corretos

#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’: [

{...

#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’: [

{...

#2: Eu chamo API, tu chamas API...DELETE /api/events/10

----------------------------------------HTTP/1.1 204 No Content

#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)

#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

#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)

#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

#3: HATEOAS

Hypermedia

As

The

Engine

Of

Application

State

Comofas/

*altamente opinativo!

Library recomendada: Restler Classes puras + ORM + Restler = API RESTful e documentada

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)

Library recomendada: Restler Classes puras + ORM + Restler = API RESTful e documentada

DocumentaçãoCódigo- Word- User

Exemplo prático:

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

Framework recomendado: Laravel/Lumen Resources automatizados em Controllers + framework

Pattern não-recomendado: closures Pattern recomendado para comprar seu ticket para o inferno

That’s all,folks!

- Richardson’s API Maturity Model- API versioning discussion- HTTP Headers spec- HTTP Verbs - Wikipedia- HTTP Verbs - spec