Boas práticas no desenvolvimento de APIs RESTful

None

Antes de qualquer coisa, é preciso esclarecer alguns termos usados dentro do universo REST, que serão utilizados constantemente neste texto. São significados que podem divergir dependendo do contexto. 

Recursos: são as entidades que a API pode gerenciar (ex: usuário e empresa). 

URI (Uniform Resource Identifier): é o identificador do recurso, que deve ser único. 

Endpoint: de forma simplificada, é o que vem após o URN. Um exemplo hipotético: para adicionar uma empresa no banco de dados, é feita uma requisição POST à API no URL https://site.com/api/empresas e segue a seguinte lógica no universo REST: 

Métodos: são os métodos de requisição HTTP, também conhecidos como HTTP Verbs (verbos HTTP). 

Neste artigo, você vai encontrar convenções usadas durante a construção de uma API que podem torná-la mais segura e consistente. 

Utilizando HTTP do jeito certo

Uma requisição HTTP pode ser realizada com base em alguns métodos. Dentre os mais utilizados estão: (GET, PUT, POST e DELETE). É comum dar o nome do recurso aos endpoints e utilizar os métodos para diferenciar a função do endpoint em questão. 

Exemplos de gerenciamento do recurso empresa: 

GET /empresas: solicita todas as empresas cadastradas; 

POST /empresas: efetua cadastro de uma nova empresa; 

PUT /empresas: atualiza informações de uma empresa com base em um identificador passado na requisição; 

DELETE /empresas: deleta uma empresa do banco de dados com base em um identificador passado na requisição. 

Note que não foi criado um URI diferente para cada ação da API como criarEmpresa ou deletarEmpresa. A API foi configurada para ter o mesmo endpoint para todas as funções e diferenciá-las apenas pelo método da requisição. 

Sobre o uso de plurais - É uma convenção utilizar o plural nos URIs para disponibilizar o recurso em questão. Exemplo: /empresas ao invés de /empresa. 

Um ponto importante que vale ressaltar é que o método GET não deve ser utilizado para efetuar alterações nos dados armazenados, como adicionar, atualizar ou deletar. Utilize os demais métodos para estas ações. 

Padronização e tratamento de erros

Trate as mensagens para evitar o retorno de erros internos da aplicação ao usuário final e procure sempre detalhá-los e evitar mensagens genéricas. 

Por exemplo: você está inserindo um novo usuário em um banco de dados MySQL e foi retornado um erro específico do banco. Ao invés de devolver a requisição com a mensagem original do erro, trate-a para se tornar mais amigável e evitar revelar informações sensíveis sobre o banco. 

Quanto ao detalhamento do erro, seja o mais específico possível. No lugar de devolver uma mensagem simples como “Não foi possível cadastrar o usuário”, deixe o motivo o mais claro possível, como “O e-mail informado já está cadastrado”. 

Procure padronizar as mensagens de erro, utilizando sempre o mesmo idioma e linguagem. Ao responder à chamada com um erro, utilize os cabeçalhos HTTP para identificar o tipo do erro retornado. 

4xx- Client error: um erro cujo código inicia-se com o número 4 indica que o erro foi causado por alguma falha por parte do client. Dentre os principais, estão inclusos: 

400 Bad Request: o servidor não entendeu o que o client está solicitando. 

401 Unauthorized: o client não está autenticado e não tem autorização para acessar o endpoint. 

403 Forbidden: o client está autenticado e a requisição é válida, porém não tem permissão de acesso àquele endpoint. 

404 Not Found: o endpoint não foi localizado.

5xx- Server error: um erro cujo código inicia-se com o número 5 indica que foi causado por alguma falha por parte do servidor. Dentre os principais, estão inclusos: 

500 Internal Server Error: o servidor não conseguiu lidar com o erro. 

503 Service Unavailable: o servidor está indisponível para responder a requisição, onde a causa mais comum é sobrecarga. 

504 Gateway Timeout: o tempo de resposta expirou e o servidor não conseguiu responder a tempo. 

Filtragem

Procure adicionar filtros nas chamadas a fim de reduzir a largura da banda de dados transportados, tempo de processamento e de resposta do servidor, assim reduzindo custos desnecessários e contribuindo com a disponibilidade do serviço. 

Procure também utilizar sub recursos para as relações durante as consultas e filtros. Por exemplo: para resgatar os empregados de uma determinada empresa, construa um endpoint semelhante a:

Segurança

Utilize um sistema de autenticação para restringir o acesso à API, seja por meio de usuários autenticados por um token criptografado ou qualquer outra forma considerada segura. 

Uma camada a mais de segurança é a configuração do CORS (Cross-Origin Resource Sharing) para evitar que URLs não autorizados façam requisição à API. 

Faça validação e tratamento nos inputs, para evitar a injeção de scripts na aplicação que possam comprometer sua integridade. 

Conclusão

Suas APIs tem mais chances de cumprirem a missão e deixar seus clientes satisfeitos se você aplicar cuidados simples, como os descritos acima.  

Boas práticas como estas podem ser uma parte do que transformará a forma como as empresas enxergam você, de um programador comum, a alguém que se preocupa com uma entrega de qualidade. 

---

Quer conversar sobre DX e APIs? Clique aqui e marque uma reunião.

Este artigo foi escrito por Henry Kimura e publicado originalmente em Prensa.li.