Este documento fornece uma introdução sobre APIs REST, definindo o que é REST e hipermídia, discutindo como projetar e implementar uma API REST passo a passo e mencionando algumas ferramentas e bibliotecas úteis. O documento explica como entender o fluxo de trabalho da API, construir uma máquina de estados, criar tipos de mídia e implementar a API usando exemplos de pedidos e pagamentos em uma lanchonete.

1. Descobrindo
APIs REST

2. Guilherme Cavalcanti
github.com/guiocavalcanti

4. Por quê?

5. 1º
Definição
Hermética

6. 2º
apotonick/roar
kevinswiber/siren
jsonapi.org
Como?
Por quê?
intridea/grape
lostisland/sawyer
caelum/restfulie

7. 3º
What the f* is
Representational State Transfer

8. “I am getting frustrated by the number of
people calling any HTTP-based interface a
REST API.”
–Roy Fielding

10. Como?

11. •
Problema conhecido por todos
•
Passo a passo para projetar e implementar uma API
REST
•
Erros comuns, trade-offs e falácias

12. O que é rest e hypermedia?

13. •
Estilo arquitetural
•
Restrições

14. O que é REST/Hypermedia?
•
Construção de sistemas distribuídos
•
Em 99% dos casos sistemas que funcionam na
Web
•
Aplicativos mobile conversando com APIs
•
Aplicativos Web convesando com Aplicativos Web
•
Walledgarden

15. O processo
1. Entender o workflow que a API irá implementar
2. Construir máquina de estados
3. Construir media types
4. Implementar :)

16. Entender o workflow

17. Entender workflow
•
Pensar em termos de processos de negócio
•
Quantos e quais passos serão necessários?

18. Pagamento
Pedido

19. O Problema
•
Ciclo de pedido
•
Ciclo de pagamento
•
Independentes
•
Comunicação assíncrona
através de message queue
•
Maximiza throughput

20. Pagamento
Pedido
Message Queue

21. Simplificado
•
Na verdade são 3 ciclos independentes
•
Mais lucros
•
Dica: Starbucks Does Not Use Two-Phase Commit

22. Criar máquina de estados

23. Criar máquina de estados: cliente
Pedir
Sanduíche
preparado
Atualizar
Pagar
Pagamento
realizado
Pegar
Sanduíche
entregue

24. Caixa
Escolher
pedido
Sanduíche
Escolhido
Lançar
pagamento
Pagamento
Lançado

25. Construir media type

26. ( o que é media type? )

27. “To some extent, people get REST wrong
because I failed to include enough detail on
media type design within my dissertation.
That’s because I ran out of time […]”
–Roy T. Fielding

28. Media types
•
É o que o cliente precisa saber para entender:
•
Comportamento (ou seja, quais transições saem
de ume estado)
•
Semântica de alguns atributos da representação

29. Exemplo: text/html
•
Ao clicar no <a>: Requisição GET
para href
•
Ao submeter um <form>: Requisição method para
action

30. Exemplo: text/html
•
O browser só precisa entender o media type.
•
Tanto faz se você está vendo o extrato da sua conta
do banco ou um verbete na Wikipedia
•
media type = comportamento + semântica

31. Exemplo: APIs
•
Erros de validação
•
Internacionalização de mensagens
•
URLs

32. Media types
•
É por isso que sempre dizem que APIs REST não
precisam de Documentação
•
Você só precisa descrever os media types utilizados
•
A semântica dos métodos HTTP já é bem definida
•
Utilizado nos cabeçalhos Accept e Content-­‐type

33. Voltando:
Construir media type

34. Voltando:
Construir media type

35. Sanduíche
Variante
Feito por terceiros
application/vnd.subway.sanduiche-­‐v1+json
Nome

36. Sanduíche: Semântica
•
id
•
created_at
•
pao
•
queijo
•
status
•
updated_at

37. Pagamento: Semântica
•
id
•
created_at
•
numero_cartao
•
expira_em
•
valor

38. Semântica
•
Atributos que tem o mesmo significado para todos
os recursos da API
•
Comportamentos inesperados (erros de validação)

39. Comportamento: Relacionamentos
{
"links":
[
{
"rel":
"self",
"href":
"/pedidos/1"
},
{
"rel":
"pagamento",
"href":
"/pagamentos/pedidos/1"
}
]
}

40. Comportamento: Relacionamentos
•
Representam as transições da nossa máquina de
estados
•
Aumentam o desacoplamento
•
O cliente não precisa saber URLs a priori

41. Mas… Quais métodos utilizar?

42. “[…] methods are not given meaning by the media
type. Instead, the media type tells the client either
what method to use (e.g., anchor implies GET) or how
to determine the method to use (e.g., form element
says to look in method attribute). The client should
already know what the methods mean (they are
universal) and how to dereference a URI.”
–Roy T. Fielding

43. HTTP Methods
•
GET
•
POST
•
PUT
•
PATCH
•
DELETE
•
OPTIONS

44. “ Rails is not restful “
Kind of comment…

45. Implementar

46. Pedir
Sanduíche
preparado
Atualizar
Pagar
Pagamento
realizado
Pegar
Sanduíche
entregue

47. Fazer pedido: Requisição
POST
/pedidos
HTTP/1.1
Accept:
application/vnd.subway.sanduiche-­‐v1+json
{
"pao":
"3queijos",
"queijo":
"suíço",
"recheio":
"club"
}

48. Fazer pedido: Resposta
HTTP/1.1
201
Created
Content-­‐type:
application/vnd.subway.sanduiche-­‐v1+json
{
"id":
"1",
"created_at":
"2013-­‐10-­‐23T05:02Z",
"updated_at":
null,
"pao":
"3
queijos",
"queijo":
"suíço",
"recheio":
"club",
"status":
“em
preparo",
"links":
[
{
"rel":
"self",
"href":
"/pedidos/1"
},
{
"rel":
"pagamento",
"href":
"/pagamentos/pedidos/1"
}
]
}

49. Atualizar pedido: Requisição
PATCH
/pedidos/1
HTTP/1.1
Accept:
application/vnd.subway.sanduiche-­‐v1+json
{
"queijo":
"cheddar"
}

50. Atualizar pedido: Resposta
HTTP/1.1
200
Ok
Content-­‐type:
application/vnd.subway.sanduiche-­‐v1+json
{
"id":
"1",
"created_at":
"2013-­‐10-­‐23T05:02Z",
"updated_at":
null,
"pao":
"3
queijos",
"queijo":
"cheddar",
"recheio":
"club",
"links":
[
{
"rel":
"self",
"href":
"/pedidos/1"
},
{
"rel":
"pagamento",
"href":
"/pagamentos/pedidos/1"
}
]
}

51. Atualizar pedido: Erro
HTTP/1.1
409
Conflict
Content-­‐type:
application/vnd.subway.sanduiche-­‐v1+json
{
"id":
"1",
"created_at":
"2013-­‐10-­‐23T05:02Z",
"updated_at":
null,
"pao":
"3
queijos",
"queijo":
"suiço",
"recheio":
"club",
"links":
[
{
"rel":
"self",
"href":
"/pedidos/1"
},
{
"rel":
"pagamento",
"href":
"/pagamentos/pedidos/1"
}
]
}

52. Como saber se é possível mudar o
pedido?
OPTIONS
/pedidos/1
HTTP/1.1
HTTP/1.1
200
Ok
Allow:
GET,
PATCH

53. Pagar pedido: REQUISIÇÃO
•
Lembra do media type?
•
Utilizar relacionamentos

54. Pagar pedido: REQUISIÇÃO
GET
/pagamentos/pedidos/1
HTTP/1.1
Accept:
application/vnd.subway.sanduiches-­‐v1+json
{
"numero_cartao":
"123312",
"expira_em":
"12/12",
"valor":
"12.45"
}

55. Ponto de vista do caixa: fila de
sanduíches
GET
/pedidos
HTTP/1.1
Accept:
application/vnd.subway.sanduiches-­‐v1+json
{
"total":
12,
"page":
1,
"per_page":
10,
"items":
[
{
"id":
“1”,
“status”:
"pago"
…
},
{
"id":
“2”,
“status”,
“em
preparo"
…
}
]
}

56. Listar pedido: media type
•
É necessário criar seu próprio media type?
•
Não! Já existem vários:
•
collection+json
•
atom+xml

57. Gems

58. roar
beer
=
Beer.new(:title
=>
"Lonestar
Beer")
beer.post(order.links[:items])

59. jsonapi.org
•
Media type de propósito geral
•
Links, Coleções, etc

60. Obrigado :)

61. Referências
•
http://www.infoq.com/articles/webber-rest-workflow
•
http://www.enterpriseintegrationpatterns.com/ramblings/
18_starbucks.html
•
http://roy.gbiv.com/untangled/2008/rest-apis-must-behypertext-driven
•
http://github.com/apotonick/roar
•
http://github.com/intridea/grape
•
http://jsonapi.org