O documento apresenta boas práticas para o desenvolvimento de uma API RESTful, incluindo versionamento de API, representação de recursos, HATEOAS, paginação, tratamento de erros e segurança.

1. Boas práticas no desenvolvimento
de uma RESTful API
Fernando Camargo
● Graduando em Engenharia de Computação -
UFG
● Fibonacci Soluções Ágeis
● Java EE, Android, Grails, Node.JS e front-end
web
● Artigos: Construindo uma RESTful API Parte 1
e 2 – Java Magazine

2. Boas práticas no desenvolvimento
de uma RESTful API
Agenda:
● Introdução ao REST
● Boas práticas:
➔ Versionamento
➔ Representação
➔ HATEOAS
➔ Representação parcial e paginação
➔ Erros
➔ Segurança
➔ Cache

3. Introdução ao REST

4. Websites vs Webservices

5. SOAP
● Especificação
● XML → maior gasto de rede
● Complexidade → dificuldade para HTML5 e
mobile
● Comunicação entre servidores → segurança
assumida
● Sem cache

6. REST
● Estilo arquitetural
● Diversos formatos → JSON ocupa menos
rede
● Simplicidade → clientes magros
● Comunicação entre cliente e servidor
● Alto poder de cache
HTML5 + mobile ready!

7. Seis regras do REST
● Interface uniforme
● Stateless
● Cacheável
● Cliente-Servidor
● Sistema em camadas
● Código sob demanda (opcional)

8. Interface uniforme
● Contrato entre cliente e servidor
● Recursos no lugar de ações
● URLs identificam recursos
● Operações identificadas por HTTP Methods
GET /produtos
GET /produtos/1

9. Interface uniforme
● Representações no lugar de recursos
(REpresentational State Transfer – REST)
● Hypermedia
● Mensagens auto-descritivas

10. Stateless
● Requisições auto-contidas
● Sem manutenção de estado do lado do
servidor

11. Cacheável
● Possibilidade de fazer cache dos resultados
● Melhora na performance

12. Cliente-Servidor
● Separação de responsabilidades
● Desenvolvimento independente, respeitando o
contrato

13. Sistema em camadas
● Camadas do servidor invisíveis ao cliente
● Aumento de escalabilidade

14. Código sob demanda (Opcional)
● Possibilidade de resposta com código
executável

15. HTTP Methods
● Ações sobre os recursos
● Podem ser ou não idempotentes

16. HTTP GET
● Usado para se obter determinado(s) recurso(s)
● Resposta: representação em formato desejado
● Idempotente
GET /recursos
GET /recursos/1

17. HTTP DELETE
● Usado para deletar recurso(s)
● OK ou Not Found
● Idempotente
DELETE /recursos/1

18. HTTP HEAD
● Usado para obter metadados do(s) recurso(s)
● Resposta: representação com metadados
relevantes
● Idempotente
HEAD /recursos
HEAD /recursos/1

19. HTTP POST
● Usado para se criar um recurso (sem
especificar ID) ou fazer uma atualização parcial
de um existente
● Resposta: Created + Location ou OK
● Não idempotente

20. HTTP PUT
● Usado para se fazer uma atualização
completa (ID na URL) ou criar um recurso
(especificando ID)
● Resposta: OK
● Idempotente

21. Boas práticas

22. Versionamento
● Quebra de contrato → nova versão
● Cliente especifica versão invocada
● Prazos de migração para versões novas
● Número de versão → baixa granularidade (v1,
v2, v3, etc)
● URL vs Content-Type/Accept

23. Versionamento - URL
Versão especificada na URL
● GET api.joincommunity.com.br/v1/palestrantes
Accept: application/json
● POST
api.joincommunity.com.br/v1/palestrantes
Content-Type: application/json
✔ Versionamento da API como um todo

24. Versionamento – Content-
Type/Accept
Versão especificada nos headers.
● GET api.joincommunity.com.br/palestrantes
Accept: application/vnd.palestrante-v1+json
● POST api.joincommunity.com.br/palestrantes
Content-Type: application/vnd.palestrante-
v1+json
✔ Versionamento de representações dos
recursos

25. Representação
● Diferentes representações disponíveis: XML vs
JSON
● camelCase em nome dos campos
● Datas em ISO 8601: yyyy-MM-
dd'T'HH:mm:ss.SSS'Z'

26. HATEOAS
Hypermedia as the Engine of Application State
● Recursos identificados por URLs
● Hypermedia → hyperlinks para recursos
relacionados
{
“href”:
“api.joincommunity.com.br/palestrantes/1”
}

27. Representação parcial
● Apenas campos necessários como resposta
ao GET
● Parâmetro fields
GET api.joincommunity.com.br/palestrantes?
fields=nome,email
{“href”:”[...]”, “nome”:”[...]”, “email”:“[...]”}

28. Representação parcial
● Recursos relacionados representados de
forma incompleta por padrão
● Parâmetro expand
GET
api.joincommunity.com.br/palestrantes/1?
expand=endereco
{
“href”: “[...]”,
“endereco”: {“href”: “[...]”}
}

29. Paginação
● Parâmetros offset e limit
● Links para next, first, previous, last, etc.
● Campo items

30. Paginação
{
“href”: “[...]/palestrantes”,
“next”: {“href”: “[...]/palestrantes?offset=10”},
[…],
“items”: [
{[…]}, {[…]}, {[…]}, {[…]}, {[…]}, {[…]},
{[…]},
{[…]}, {[…]}
]

31. Erros
● Status HTTP
● Código que identifica o erro
● Mensagem destinada ao usuário final
● Mensagem destinada ao desenvolvedor
● URL para documentação

32. Erros
409 Conflict
{
“status”: 409,
“code”: 145,
“message”: […],
“developerMessage”: […],
“moreInfo”: “[...]/docs/api/errors/145”
}

33. Segurança
● Stateless → autenticação por requisição
● Identificação do usuário atrás de um token
● Autorização baseada em recursos e não em
URLs
● OAuth 1.0a e OAuth 2.0

34. Cache
● Performance e escalabilidade
● ETag
● 304 Not Modified
GET /palestrantes/1
ETag: “62wsc482nsadf742f7831”
Body:
{[...]}

35. Cache
GET /palestrantes/1
If-None-Match: “62wsc482nsadf742f7831”
● 304 Not Modified
● ETag: “2tfh892fds982nksaf8932”
Body:
{[...]}

36. Obrigado!
● E-mail: fernando.camargo.ti@gmail.com