REST-fuuuu
RESTful e a polícia do HTTP

Igor Santos who?
- Desenvolvedor PHP desde os 16 (~10 anos)
- Trabalho com APIs REST: ~4 anos
- Desenvolvedor React: ~2 ano
- Já mexi com Ruby, mas...
- Já brinquei com C e Python mas…
- Já me diverti com Ember mas…
Atualmente, sou Freelancer remoto Full-stack na
Join the network! Talk to me :D

Remoto.
MESMO.

RESTful

RESTful……who?
REpresentational
State
Transfer
-ful: completo, pleno
Normalmente (sempre?) baseado em HTTP(S)

RESTful……who?
Martin Fowler & Leonard Richardson, 2010: Steps toward the glory of REST

RESTful……who?
Martin Fowler & Leonard Richardson, 2010: Steps toward the glory of REST
Zoeira
REST de verdade

#0: O pântano do POX*
✓ Comunicação sobre o HTTP
✗ HTTP = protocolo facilitador de rede, somente
✗ Verbos HTTP? GETPOST all the things!
*POX: Plain Old XML

#0: O pântano do POX* *POX: Plain Old XML

#0: O pântano do POX* *POX: Plain Old XML
POST /api/
<listEvents date="2016-10-22"/>
----------------------------------------
HTTP/1.1 200 OK
<eventsList>
<event id="10">
<dates begin="2016-10-22">
<topics>
<topic>HTTP</topic>
<topic>REST</topic>
</topics>
[...]

#0: O pântano do POJ* *POJ: Pure and 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!
AKA entidades

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

#1: Resources RPC!
POST /api/events/search
{ 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 Consultas
Criação
Edição
Remoção
X X
POST /clientes/buscar
GET /clientes

#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
POST /clientes/apagar/2
DELETE /clientes/2

#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
POST /clientes/edit/27
PUT /clientes/27

#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

#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

#2: Eu chamo API, tu chamas API...
GET /api/events?date=2016-10-22
----------------------------------------
HTTP/1.1 200 OK
[
{
"id": 10,
"start": "2016-10-22",
"topics": [ "HTTP", "REST" ],
"speakers": [
{
...

#2: Eu chamo API, tu chamas API...
POST /api/events
{ "start": "2016-10-22", ... }
----------------------------------------
HTTP/1.1 201 Created
[
{
"id": 10,
"start": "2016-10-22",
"topics": [ "HTTP", "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 formato que você quer
- 422: sabe nem escreve direito, mano
- 500: CORRÃO PARA AS MONTANHAS
- 501: não sei fazer isso não

Árvore de
decisão
de códigos HTTP

#2.5: RESTful-ish
Stateless, formats, versioning...

#2.5: RESTful-ish
2. Stateful
- HTTP = stateless
- Stateless <> sessão

#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
2. Stateful
- HTTP = stateless
- Stateless <> sessão
- API <3 sessão
- API + HTTP + sessão =
- HTTP Cookie: inseguro no geral
- HTTP Auth: autentica o usuário inicialmente
- JSON Web Token: mantém o estado do lado do
cliente de modo seguro, livrando o servidor disso

#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 - ou nenhum,
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

#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

#3: HATEOAS
Links definem como se mover
dentro da API.
Em teoria, permitiria aplicações
automatizadas, consumidoras
de APIs.

#3: HATEOAS
Links definem como se mover
dentro da API.
Na prática, pode ser usado para
automatizar certas atividades
numa aplicação.

#3: HATEOAS
JSON API Spec
- Uma especificação de verdade para APIs!

#3: HATEOAS
JSON API Spec
- Uma especificação de verdade para APIs!
- Bem completa, complexa mas bem poderosa
- Dá pra fazer um monte de coisas com ela
- Muito legal <3

#3: HATEOAS
JSON API Spec
- Uma especificação de verdade para APIs!
- Bem completa, complexa mas bem poderosa
- Paginação e navegação entre recursos
- Requisição de recursos relacionados no mesmo payload
- Meta informações sobre o request
- Formato definido entre requests de uma única ou múltiplas
entradas, dados de identificação
e atributos, relacionamentos, etc

Comofas/
*altamente opinativo!

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

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

Library recomendada: Restler
Classes puras + ORM + Restler = API RESTful e documentada
Documentação
Código
- Word
- User
Exemplo prático:
OUTDATED

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

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

Pattern não-recomendado: closures

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

Testes?
Quer avaliar se a
API tá funcionando
como devia?
Postman
for the rescue!
Ou Apiary .

Se perdeu?
Tá faltando
documentação?
Swagger,
API Blueprint,
Apiary, RAML,
Postman,
etc.

Learn more about the
opportunities, come talk to me :)
Do you speak English?
Do you feel you’re great at what you do?
Looking for good clients, great pay, awesome teams and freedom?

That’s all,
folks!
- Richardson’s API Maturity Model
- API versioning discussion
- HTTP Headers spec
- HTTP Verbs: Wikipedia / Spec
- JSON API spec
- Postman
- Toptal Engineering Blog
*.com/igorsantos07
*.com/igorsantos07
*.com/in/igorsantos07
Portfolio: freelancer.igorsantos.com.br
Apply: toptal.igorsantos.com.br

That’s all,
folks!
Peço desculpas por todas as piadas
e trocadilhos ruins usados nesta
palestra. Carlos Alberto de Nóbrega
não esteve envolvido com a
mesma.
*.com/igorsantos07
*.com/igorsantos07
*.com/in/igorsantos07
Portfolio: freelancer.igorsantos.com.br
Apply: toptal.igorsantos.com.br