...

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

Assunto Primário

Explicação. Exemplo para links e anexos.

O fonte do exemplo citado pode ser baixado a partir do seguinte link:

Colleague Report.zip

Exemplo de macro para bloco de código:

Macro para código.
Em editar é possível selecionar a linguagem.

Exemplo de Nota

Exemplo de Observação

Assunto Secundário

Assunto, exemplo com marcadores. A seguir apenas um passo.

• Marcador.
• Marcador.

Image Removed

Figura 1 - Exemplo de imagem (centralizada). Legenda negrito e justificada.

Assunto Secundário

Comentário sobre o assunto. Macro para passo a passo.

Acompanhe os passos a seguir:

Abaixo é utilizado o exemplo de interação passo a passo. Facilita o entendimento.

...

...

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

...

• Um espaço anterior, + um marcado, + um epaço ao final.

Image Removed

Figura X - Exemplo de Figuara e legenda (centralizados).

...

...