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.

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