Boas práticas no desenvolvimento de uma RESTful API

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

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

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

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!

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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'

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

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”:“[...]”}

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”: “[...]”}
}

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

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

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

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

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

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

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

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

Boas práticas no desenvolvimento de uma RESTful API

Mais conteúdo relacionado

Mais procurados (20)

Destaque (20)

Semelhante a Boas práticas no desenvolvimento de uma RESTful API (20)

Último (6)

Boas práticas no desenvolvimento de uma RESTful API