Histórico da Página
...
APIs Publicas são todas as APIs que podem ser acessadas por clientes externos aos times de desenvolvimento do fluig.
Erros
...
Estrutura de URLs
Os caminhos definidos para cada endpoint devem ser de fácil leitura e significativos para o cliente para facilitar a sua descoberta e adoção.
Exemplo de URLs amigáveis:
https://fluig.totvs.com/api/users/{id}
https://fluig.totvs.com/api/workflow/{id}?action=execute
https://fluig.totvs.com/api/users/{alias}/communities
Exemplo de URLS NÃOamigaveis e que deve ser evitadas:
https://fluig.totvs.com/api/communty/listCommunities
https://fluig.totvs.com/api/communty/listCommunitiesWithRelevance
https://fluig.totvs.com/api/correlationquestion/create
https://fluig.totvs.com/api/user/create
https://fluig.totvs.com/api/user/delete
https://fluig.totvs.com/api/document/permissions?documentId={id}
Apesar de o padrão definido no documento RFC 7230 da especificação do HTTP 1.1 não definir um tamanho maximo para a url nenhum endpoint do fluig deve ser identificado com uma url maior que 2000 caracteres para garantir que todos os navegares modernos sejam suportados
| Informações |
|---|
Mais informações sobre a escolha do valor máximo de caracteres pode ser consultada em: https://blogs.msdn.microsoft.com/ieinternals/2014/08/13/url-length-limits/ |
Métodos suportados
Endpoints devem usar os métodos HTTP adequados e devem respeitar a idempotência da operação.
Na tabela abaixo serão listados os métodos que DEVEMser suportados. Nem todos os endpoints devem suportar todos os métodos, mas os que usarem DEVEM respeitar a utilização conforme descrita.
| Método | Descrição | Idempotente |
|---|---|---|
| GET | Retorna o valor corrente do objeto. | Sim |
| PUT | Sobrescreve o objeto ou cria um novo objeto quando aplicável. | Sim |
| DELETE | Exclui o objeto. | Sim |
| POST | Cria um novo objeto ou submete um comando ao objeto. | Não |
| HEAD | Retorna os metadados de um objeto em requisições do tipo GET. Endpoints que suportam o método GET PODEM suportar o método HEADER. | Sim |
| PATCH | Aplica uma atualização parcial no objeto. | Não |
| OPTIONS | Retorna informações sobre uma requisição; ver abaixo para mais detalhes. | Sim |
Post
Operações do tipo POST DEVEM retornar a localização de qualquer objeto criado que tenha um identificador.
Por exemplo: Um serviço responsável por criar um usuário descrito como:
| Bloco de código | ||
|---|---|---|
| ||
POST http://fluig.totvs.com/api/users |
Deveria responder com algo similar a:
| Bloco de código | ||
|---|---|---|
| ||
201 Created
Location: https://fluig.totvs.com/api/users/10 |
Onde 10 é o id do novo usuário criado.
PUT x PATCH
Apesar de ambos atualizarem um objeto é importante notar que existe uma diferença na implementação destes métodos.
PUT DEVE ser considerado uma substituição total do objeto, ou seja, caso o cliente deixe de enviar uma propriedade para ser atualizada ela será considerada nula e poderá inadvertidamente remover valores do objeto.
PATH foi padronizado pelo IETF como o método usado para atualizar um objeto de forma incremental (ver RFC 5789), ou seja, apenas as propriedades informadas pelo cliente serão atualizadas.
Padrões de cabeçalhos de requisição
A utilização destes cabeçalhos não é obrigatória para todos os endpoints mas os que os usarem DEVEM obedecer as regras descritas aqui.
| Header | Tipo | Descrição |
|---|---|---|
| Authorization | literal | Cabeçalho usado para autorização das requisições |
| Date | data | Data e hora da requisição com base no calendário do cliente no formato estipulado em RFC 5322 |
| Accept | enumerador de tipo de conteúdo | O tipo de conteúdo esperado para a resposta como por exemplo:
De acordo com os padrões HTTP, este valor é apenas uma dica para o servidor e as respostas PODEM retornar valores em formatos diferentes dos informados. |
| Accept-Encoding | Gzip, deflate | Endpoints DEVEM suportar codificação GZIP e DEFLATE quando aplicável. |
| Accept-Language | "en", "es", "pt" | Especifica o idio preferencial da resposta. Endpoints DEVEM suportar e respeitar estes valores em casos em que uma mensagem é retornada ao usuário. |
| Content-Type | tipo de conteúdo | Tipo do conteúdo informado na requisição. |
Mensagens
Durante a construção das mensagens que serão transmitidas entre o cliente e endpoint deve-se garantir a consistência entre nomes de propriedades e objetos quando os mesmo fizerem parte de um mesmo grupo ou assunto.
Mensagens de retorno do endpoint para o cliente devem obedecer a estrutura definida para mensagens de erro ou mensagens de sucesso
| Âncora | ||||
|---|---|---|---|---|
|
Mensagem de erro
Todos as respostas de erro (códigos HTTP 4xx e 5xx) devem retornar uma mensagem contendo obrigatoriamente os campos a seguir:
...
Visão Geral
Import HTML Content
Conteúdo das Ferramentas
Tarefas