Palestra apresentada no DevFest Cerrado 2016 sobre design (independente de linguagem) de RESTful APIs.

1. Fernando Camargo
Apresentado por
Mestrando em Engenharia de Computação, UFG
Design de RESTful APIs

2. Tópicos
1. Introdução ao REST
a. Por quê?
b. Seis Regras
c. Métodos e Status HTTP
2. Boas Práticas
a. Versionamento
b. Formato de Representação
c. HATEOAS
d. Representação Parcial e Paginação
e. Respostas de Erro
f. Segurança
g. Cache

3. Introdução ao REST

4. Web Sites

5. Web Services (SOAP)

6. Web Services (REST)

7. Por que REST?
•Menor gasto de rede
•Menor complexidade
•SOAP pensado para servidores
•REST pensado para dispositivos leves
•Possibilita cache

8. Seis Regras
REST é um Padrão Arquitetural sobre o HTTP com
as regras:
•Interface Uniforme
•Stateless
•Cacheável
•Cliente-Servidor
•Sistema em Camadas (Possibilidade)
•Código sob Demanda (Possibilidade)

9. Interface Uniforme
•Baseado em Recursos, não Ações
•Recursos identificados por URL
•Ações vinculados aos Métodos HTTP

10. Interface Uniforme
•Baseado em Recursos, não Ações
•Recursos identificados por URL
•Ações vinculados aos Métodos HTTP
•URLs com substantivos no Plural

11. URLs Erradas
•/listarProdutos
•/obterProdutos/1
•/criarProdutos
•/deletarProduto/1

12. URLs Corretas
•/produtos
•/produtos/1

13. Interface Uniforme
•Representational State Transfer
•HATEOAS: Hypermedia as the Engine of
Application State
•Mensagens autodescritivas

14. Métodos HTTP
✔Idempotência: múltiplas requisições não
alteram o resultado
•GET: obtenção
•HEAD: obtenção de metadados
•DELETE: remoção
•POST (não idempotente): criação sem
ID/atualização parcial
•PUT: atualização completa/criação com ID

15. Status HTTP
• 200 OK
• 201 Created
• 304 Not Modified
• 400 Bad Request
• 401 Unauthorized
• 403 Forbidden
• 404 Not Found

16. Boas Práticas

17. Versionamento
✔Evitar quebra de contrato com clientes
Tipos de versionamento:
•Através de URL
•Através de Tipo de Media

18. Formato de Representação
✔Suportar mais de um formato (XML e JSON)
Especificação do formato desejado:
•Através de URL (pouco usado)
•Através de Tipo de Media (Accept/Content-
Type)

19. Exemplos de requisições
• GET api.devfest.com.br/v1/palestrantes
Accept: application/json
• GET api.devfest.com.br/v1/palestrantes/23
Accept: application/json
• POST api.devfest.com.br/v1/palestrantes
Content-Type: application/json

20. Exemplos de requisições
• GET api.devfest.com.br/palestrantes
Accept: application/vnd.palestrantes-v1+json
• GET api.devfest.com.br/palestrantes/23
Accept: application/vnd.palestrantes-v1+json
• POST api.devfest.com.br/palestrantes
Content-Type: application/vnd.palestrantes-
v1+json

21. Representação parcial
• Parâmetro “fields”
• GET api.devfest.com.br/palestrantes?
fields=nome,endereco
{
“href”: “https://api.devfest.com.br/palestrantes/23”,
“nome”: “Fernando Camargo”,
“endereco”: {
“href”: “https://api.devfest.com.br/enderecos/23”
}
}

22. Representação parcial
• Parâmetro “expand”
• GET api.devfest.com.br/palestrantes?
fields=nome,endereco&expand=endereco
{
“href”: “https://api.devfest.com.br/palestrantes/23”,
“nome”: “Fernando Camargo”,
“endereco”: {
“href”: “https://api.devfest.com.br/enderecos/23”,
“logradouro” : “Rua 31-A”, ...
}
}

23. HATEOAS
• Atributo “href”
{
“href”: “https://api.devfest.com.br/palestrantes/23”,
“nome”: “Fernando Camargo”, …,
“endereco”: {
“href”: “https://api.devfest.com.br/enderecos/23”,
“logradouro” : “Rua 31-A”, ...
}
}

24. HATEOAS
• Paginação
{
“href”: “https://api.devfest.com.br/palestrantes”, …
“next”: {“href”: “...”},
“previous”: {“href”: “...”},
“last”: {“href”: “...”},
“items”: [
{“href”: “...”, …},
{“href”: “...”, …}, ...
]
}

25. Respostas de Erro
•Utilizar Status HTTP
•Documentar e identificar erros
•Prover URL para documentação do erro
•Prover mensagem para usuário e
desenvolvedor

26. Respostas de Erro
409 Conflict
{
“code”: 145,
“message”: “Já existe um palestrante com esse CPF.”,
“devMessage”: “Já existe um palestrante com esse CPF.
Pode ser causado por repetição de requisições.”,
“moreInfo”:
“https://dev.devfest.com.br/docs/api/errors/145”
}

27. Segurança
• Oauth 1.0a ou 2.0
• Autenticação acontece em toda requisição

28. Cache
• Header “Etag” com hash do Recurso na
resposta
• Header “If-None-Match” com o hash anterior
do Recurso em nova requisição
• 304 Not Modified

29. Dúvidas?
fernando.camargo.ti@gmail.com
Contato: