Design de APIs RESTful

WHOAMI
LEONEL MORAIS
@lmorais
leonel.morais@rivendel.com.br
Software Engineer

Agenda
● Introdução
● Design REST
● Recomendações

APIs estão presentes em quase
tudo que conhecemos

Definição de API
No contexto de desenvolvimento Web, uma API é um conjunto
definido de mensagens de requisição e resposta HTTP, geralmente
expresso nos formatos XML ou JSON.

Como projetar uma API
seguindo boas práticas?

Recursos
● Formato de rotas consistente
● Nomes de recursos
Use a versão pluralizada de um nome de recurso. Isto permite
consistência na forma que você se refere a um recurso em
particular.

Recursos
Coleções Itens
/accounts /accounts/0987
/users /users/12345

Recursos
● Ações
Prefira um endpoint que não precise de quaisquer ações especiais
para recursos individuais. Em casos onde ações especiais são
necessárias, você pode criar um resource específico para
encapsular as suas ações.

Recursos
● Ações
{
"action": {
"id": 36804748,
"status": "running",
"kind": "start"
}
}
201 Created
{
“kind”: “start”
}
POST /jobs/17403986/actions

Recursos
Evitar o aninhamento profundo de recursos, pois dificulta o
entendimento e manutenção
Não usar paths do tipo:
/users/12345/accounts/0987/transactions/112233

Recursos
Use aninhamento para indicar coleções. Por exemplo, para o caso
anterior em que uma transaction pertence a uma account, que
pertence a um user, podemos seguir o modelo abaixo:
/users/12345
/users/12345/accounts
/accounts/0987
/accounts/0987/transactions
/transactions/112233

Recursos
Não escrever endpoints que representem ações a serem executadas,
por exemplo
/getAccounts
/getAllUsers
/createUser
/updateAccounts
Para isso temos os verbos HTTP

Verbos HTTP
POST - Para criar um recurso
GET - Pra exibir detalhes de um recurso ou listar todos os
recursos
PUT - Para atualizar um recurso
PATCH - Para atualizar parcialmente um recurso
DELETE - Para remover um recurso

Verbos HTTP
POST
{
“agency”: “1234”,
“category”:
“class”,
“user_id”: “22332”
}
(não seguro, não idempotente)
POST /accounts - cria uma uma nova conta

Verbos HTTP
GET
(seguro, idempotente)
GET /accounts - lista contas
GET /accounts/123456 - exibe informações da conta 123456

Verbos HTTP
PUT
(não seguro, idempotente)
PUT /users/123 - atualiza informações do user 123
{
“name”: “cliente”,
“email”: “cliente@acme.com”,
“born_date”: “1980-01-29”,
“gender”: “male”
}

Verbos HTTP
PATCH
(não seguro, não idempotente)
PATCH /accounts/123456 - atualiza parcialmente a conta 123456
{
“status”: “active”
}

Verbos HTTP
DELETE
(não seguro, idempotente)
DELETE /users/123 - remove o user 123
DELETE /accounts/123456 - remove a conta 123456

Verbos HTTP
● NÃO use o verbo POST para todas as operações, por exemplo:
● Deletar um recurso com o verbo POST
● Listar recurso com o verbo POST
● NÃO criar recursos passando informações por query params
● POST /accounts?user_id=123&email=user@mycompany.com

Versionamento
https://api.acme.com.br/v1/accounts
HTTPS
sempre
Versão e recurso

Codigos HTTP
Retorne codigos http adequados para erros no cliente e no servidor
2xx - OK
4xx - CLIENT ERROR
5xx - SERVER ERROR

Codigos HTTP
200(OK) - A requisição foi executada com sucesso.
201(CREATED)- Recurso criado com sucesso.
202(ACCEPTED) - A requisição foi aceita com sucesso, porém será executada
assincronamente.
204(NO CONTENT) - A requisição foi executada com sucesso, mas não possui valores
para retornar no response body.

Codigos HTTP
200
(OK)
GET /users/123
{
“name”: “cliente”,
“email”: “cliente@acme.com”,
“born_date”: “1980-01-29”,
“gender”: “male”
}
200 OK

Codigos HTTP
201
(CREATED)
POST /accounts/1234/transactions
{
“id”: “9898”,
“amount”: “799.80”,
“currency”: “BRL”
}
201 Created
{
“amount”: “799.80”,
“currency”: “BRL”
}

Codigos HTTP
202
(ACCEPTED)
POST /accounts
{
“status”: “creating”
}
202 Accepted
{
“agency”: “1676”,
“user_id”: “123”
}

Codigos HTTP
204
(NO CONTENT)
DELETE /users/123
204 No Content

Codigos HTTP
400(BAD REQUEST) - O cliente enviou um payload malformado e o servidor não
conseguiu processar.
401(UNAUTHORIZED)- A requisição não executada porque não possui credenciais de
autenticação válidas para o recurso
422(UNPROCESSABLE ENTITY) - O servidor entendeu o pedido, mas não pode
processar devido a um erro de regra de negócio.
404(NOT FOUND) - O servidor não encontrou uma representação para o recurso.
429(TOO MANY REQUESTS) - O cliente enviou muitas requisições em um
determinado período de tempo.

Codigos HTTP
400
(BAD REQUEST)
POST /accounts
400 Bad Request
{
“errors”: [
{
“code”: “7745”,
“message”: “JSON parse error - Expecting property name at line
1",
“details”: “dev.acme.com.br/errors/7745”
}
]
}

Codigos HTTP
401
(UNAUTHORIZED)
POST /accounts
401 Unauthorized
{
“errors”: [
{
“code”: “7750”,
“message”: “Could not authenticate the user with credentials",
}
]
}

Codigos HTTP
422
(UNPROCESSABLE ENTITY)
POST /accounts
422 Unprocessable Entity
{
“errors”: [
{
“code”: “7897”,
“message”: “You cannot create the account for this user, the
user is inactive.",
}
]
}

Codigos HTTP
404
(NOT FOUND)
GET /accounts/12
404 Not Found
{
“errors”: [
{
“code”: “7721”,
“message”: “The requested resource does not exists",
}
]
}

Codigos HTTP
429
(TOO MANY REQUESTS)
GET /accounts/123456
429 Too Many Requests
{
“errors”: [
{
“code”: “9234”,
“message”: “Rate limit exceeded",
}
]
}

Codigos HTTP
429
(TOO MANY REQUESTS)
Para que o cliente possa controlar os limites de
requisição, devemos enviar response headers indicando os
valores remanescentes atualizados a cada request.
X-RATE-LIMIT-LIMIT: Numero de requests permitidos em uma janela de
tempo pre definida.
X-RATE-LIMIT-REMAINING: Numero de requests restantes em uma
janela de tempo pre definida.
X-RATE-LIMIT-RESET: Tempo da janela em UTC epoch seconds até que
o rate-limit seja redefinido.

Codigos HTTP
500(SERVER ERROR) - Um erro inesperado aconteceu no servidor e o mesmo não
conseguiu responder a requisição.
500 Internal Server Error
{
“errors”: [
{
“code”: “5000”,
“message”: “Something went wrong on server ",
}
]
}

Codigos HTTP
● NUNCA utilizar HTTP 500 para erros de regra de negócio.
● NÃO retornar HTTP 200 para tudo.
● Retornar HTTP 201 quando um recurso for criado.
● SEMPRE retornar a representação completa quando um recurso for criado.
● Retornar HTTP 202 quando uma requsição for aceita para ser processada async.
● NÃO retornar mensagens como: “success” ou “ok” no response body, pois é
desnecessário uma vez que o HTTP code correto é enviado

Filtros
● Para obter um conjuntos de dados filtrado por algum atributo, utilizamos query
parameters.
● É possível fazer com escopo ou até mesmo com resultados parciais, exibindo somente
campos necessários.

Filtros
● Buscas com escopo e respostas parciais
GET /accounts?status=active
GET /accounts/123456?fields=agency,balance,owner
GET /accounts?status=pending&fields=agency,owner

Paginação
● Deixar para que o client escolha o tamanho da pagina que ele deseja receber.
● Utilizar OFFSET e LIMIT para fazer a paginação
● Você pode se basear nos SGBDs que possuem clausulas limit e offset para consultas.
:)

Paginação
● Paginação com limit e offset
GET /accounts?limit=5&offset=10

Cache
● Evita tráfego desnecessário
● Diminui problemas com latência de rede e sobrecarga nos servidores
● Ficar atento ao tempo de cache invalidation
● Fazer tunning até chegar a um tempo adequado de expiração do cache
● Podemos utilizar HTTP para fazer cache :D

Cache
● O client pode solicitar ao servidor se ele possui uma cópia atualizada do recurso. O
client enviará algumas informações sobre o recurso em cache que possui e o servidor
determinará se o conteúdo atualizado deve ser retornado ou a cópia do client é a mais
recente. No caso do último, um HTTP 304 (NOT MODIFIED) é retornado.

Cache
● Cache com ETAGs
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
ETag: "88d979a0a78942b5bda05ace4214556a"
…

Cache
● Cache com ETAGs
Host: api.acme.com.br
Content-Type: application/json
If-None-Match: "88d979a0a78942b5bda05ace4214556a"

Cache
● Cache com ETAGs
HTTP/1.1 304 Not Modified
Content-Type: application/json
Content-Length: 0

Segurança
● Evitar acesso não autorizado
● Prevenção à ataques
● Sobrecarga nos servidores
● Implementações de clients não adequadas

Segurança
Isso pode ser simplificado
com um API GATEWAY

Segurança
● Kong API Gateway

API DOCS
● Documente sua API com alguma ferramenta como Swagger ou API Blueprint
● Tenha um developer portal
● Sandbox
● Exemplos de códigos e tutoriais em várias tecnologias (node, python, java, ruby,
go)
● SDKs
● Documentação de codigos de erro
● Self-service signup

API Health
● Crie um endpoint de heath check para que seja possível verificar a saúde da sua API
● Sua API só está saudável se todas as dependências estiverem ok
● Tenha na sua plataforma um API Status Page que mostre a saúde de todas as suas
APIs

API Health
GET /health
200 OK
{
“mysql”: “OK”,
“payments-api”: “NOK",
“redis”: “OK”
“elasticsearch”: “OK”
}

Recomendações
● Versione sua API
● Evite aninhamentos longos
● Use POST para criar, PUT e PATCH para atualizar
● Filtre com query parameters
● Selecione o ‘media type’ (como JSON/XML) via headers, não via PATH
● Use direito os códigos de retorno do HTTP
● Não retorne 404 para listagens com zero elementos
● Faça paginação com limit e offset
● Não permita que verbos como “create”, “update” ou “delete” façam parte do PATH das
URLs, para isso existe o HTTP

Design de APIs RESTful

Recomendados

Recomendados

Mais conteúdo relacionado

Semelhante a Design de APIs RESTful

Semelhante a Design de APIs RESTful (20)

Design de APIs RESTful