Developer Experience
6
min de leitura
23 de julho de 2020

Boas Práticas: HTTP Status

Luciana Bandeira
Developer Experience
Ajudo desenvolvedores no onboarding e nas melhores práticas de APIs para garantir a melhor Developer Experience. No meu tempo livre me dedico a livros, pesquisar (e degustar) sobremesas e sou apaixonada por viajar.
Mais sobre o autor

Há algumas boas práticas e ações que são recomendadas por nossa equipe DX para que os clientes que utilizam as APIs coloquem em prática a fim de simplificar a compreensão dos desenvolvedores durante o uso.

Na verdade, estas boas práticas também podem ser aplicadas no Portal do Desenvolvedor, para apoiar e orientar o desenvolvedor neste processo de utilização.

Em uma base diária, um dos itens que vimos facilitando a comunicação e o entendimento para o desenvolvimento no consumo de APIs é o uso correto de HTTP Status.

A padronização dos códigos de retorno que a API fornecerá ajudará o desenvolvedor e o processo de integração, assim como ajudará o desenvolvedor a extrair métricas de forma mais assertiva. Além disso, a disponibilização destas informações em seu Portal do Desenvolvedor tornará todos que consomem estas chamadas cientes destas padronizações e da representação de retorno.

Uso adequado de HTTP Status

Sabemos que muitos desenvolvedores estão bem informados em todos os processos de uso de API e estes padrões de código são conhecidos em todo o mundo, mas disponibilizar estas informações juntamente com a explicação/representação do que cada retorno significará dentro de sua integração ajudará o desenvolvedor a compreender possíveis erros de uso de forma mais fácil e rápida.

Além disso, isto permite que sua própria integração disponível para estes propósitos siga estes padrões determinados desde o início, garantindo até mesmo um melhor monitoramento e acompanhamento de tais erros.

Assumindo que, em seu primeiro API disponível para consumo, você seguiu estes padrões de código, mas que, por algum motivo, outra equipe disponibilizou uma nova API sem também seguir estes padrões. Usando este cenário de padronização como exemplo, podemos assumir, por exemplo, que seu desenvolvedor faz um POST para inserir informações, mas que estas informações já foram registradas. Deixando apenas um retorno como padrão, por exemplo, através de HTTP Status 400 e a mensagem de erro expondo este cenário não exibirá este caso em métricas, mas será uma visão geral dos vários motivos que podem causar a "bad request".

Portanto, você pode recomendar, por exemplo, HTTP Status 409 (conflict) ou 422 (unprocessable entity). Desta forma, o desenvolvedor saberá imediatamente que aquele determinado recurso já foi registrado e quando você, como proprietário da API, for extrair métricas, poderá distinguir este caso de outros 4XX possíveis mais fácil e mais assertivamente.

Como vimos, há vários fatores muito interessantes a considerar em relação às boas práticas no uso de API e também na alimentação dos Portais de Desenvolvedores. Desde que uma API vá além de simplesmente abrir uma integração, é necessário pensar sobre a experiência de seu consumo, e quanto mais clara e objetiva for a comunicação, melhor será sua API.

Aqui na Sensedia, temos equipes especialmente dedicadas a isto e que podem fornecer várias informações sobre como disponibilizar seus recursos. Vamos agora recomendar alguns artigos sobre o assunto:

Developer Experience (DX) - Alavancar o uso de suas APIsPor queé importante ter um Portal do Desenvolvedor para os negócios?Cuidados com APIs: O que é monitoramento ativo e por que é importante para suas estratégias digitais

Obrigado pela leitura!