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.
Boas práticas no desenvolvimento de uma RESTful API
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
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
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
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
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”: “[...]”}
}
31. Erros
● Status HTTP
● Código que identifica o erro
● Mensagem destinada ao usuário final
● Mensagem destinada ao desenvolvedor
● URL para documentação
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:
{[...]}