Índice

Introdução

Este documento define os padrões que devem ser adotados durante a implementação de novas APIs publicas ou privadas na plataforma do fluig incluido:

• Definir práticas e padrões consistentes para todos os endpoints das APIs do fluig;
• Garantir a utilização mais próxima possível das boas práticas estipuladas pelos padrões REST/HTTP;
• Tornar os serviços da plataforma fluig acessíveis através de APIs mais fáceis e documentadas para desenvolvedores e consumidores;
   

Comitê

Criamos um comitê interno, formado com um integrante de cada squad, para discutir e garantir a execução dos padrões definidos neste documento.

Cada um dos membros deve obrigatoriamente ser incluído no pull request de novas APIs publicas e cadas um deles é responsável por garantir a correta disseminação e implementação dentro de seu próprio time das APIs privadas.

Nomenclaturas

Cliente: Qualquer aplicativo que faça uma requisição para um endpoint do fluig.

Mensagem: Conteúdo enviado no corpo de uma requisição ou resposta do servidor.

Endpoint: Representa um método ou entidade que pode ser acessado através de uma requisição ao servidor do fluig.

Verbo: Tipo de requisição usada para acessar um endpoint (GET, POST, PUT, HEAD, etc).

API: Grupo de endpoints

APIs Privadas são todas as APIs acessíveis apenas pelos times do fluig

APIs Publicas são todas as APIs que podem ser acessadas por clientes externos aos times de desenvolvimento do fluig.

Erros

Todos as respostas de erro devem retornar uma mensagem contendo pelo menos os campos a seguir:

{
    code: "Código identificador do erro",
    message: "Literal no idioma da requisição descrevendo o erro para o cliente",
    log: "Mensagem técnica e mais detalhada do erro"
}

Erros de negócio são definidos como o cliente passando dados inválidos para o endpoint e este corretamente e intencionalmente rejeitando os dados. Todos os erros deste tipo devem obrigatóriamente retornar um código HTTP 4xx. Ex:

1. O cliente chamou um endpoint mas não estava devidamente autenticado. Deve ser retornado o código 401 - Unauthorized
2. O cliente chamou um endpoint mas mesmo estando autenticado não possui os direitos necessários para efetuar a operação. Deve retornar o código 403 - Forbidden
3. O cliente chamou o endpoint para buscar um usuário (Ex: /users/{id}) mas o usuário não existe. Deve ser retornado o código de erro 404 - Not found
4. O cliente chamou o endpoint para efetuar alguma operação mas por alguma regra de negócio a operação não pode ser concluída e não existe um código de erro HTTP apropriado para descrevê-lo. Deve ser retornado o código de error 400 - Bad Request