Histórico da Página
...
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:
Exemplo de macro para bloco de código:
Bloco de código | ||
---|---|---|
| ||
Macro para código.
Em editar é possível selecionar a linguagem. |
Exemplo de Nota
Informações | ||
---|---|---|
| ||
Insere Nota |
Exemplo de Observação
Nota | ||
---|---|---|
| ||
Insere Observação |
Assunto Secundário
Assunto, exemplo com marcadores. A seguir apenas um passo.
- Marcador.
- Marcador.
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.
...
effectDuration | 0.5 |
---|---|
history | false |
id | samples |
effectType | fade |
Card | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
|
Card | ||||
---|---|---|---|---|
| ||||
|
...
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.
Squad | Membro |
---|---|
SDK | Marcelo De Aguiar |
Identity / Portal | Paulo Roberto Francisco Junior |
LMS | Diego Lopes |
BPM | Gustavo Martins De Souza |
PAAS / Fundação | Vanei Anderson Heidemann |
ECM | Andre Felipe Joriatti |
Integração | Danilo Pacheco Martins |
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:
Bloco de código | ||
---|---|---|
| ||
{
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:
- O cliente chamou um endpoint mas não estava devidamente autenticado. Deve ser retornado o código 401 - Unauthorized
- 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
- 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
- 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
...
id | 3 |
---|---|
label | Passo 3 |
Um espaço anterior, + um marcado, + um epaço ao final.
Figura X - Exemplo de Figuara e legenda (centralizados).
...
id | 4 |
---|---|
label | Passo 4 |
...