Histórico da Página
...
| Bloco de código | ||
|---|---|---|
| ||
GET https://fluig.totvs.com/api/users/10?expand=communities.permissions
{
_expandables: ["permissions", "detailedInformation"],
id: 10,
name: "Usuário",
age: 25,
permissions: [],
communities: [{
name: "Vendas",
photoUrl: "https://fluig.totvs.com/communities/1/photo",
permissions: {
isAdmin: true,
canView: true
}
}, {
name: "Outra comunidade",
photoUrl: "https://fluig.totvs.com/communities/2/photo",
permissions: {
isAdmin: true,
canView: true
}
}],
detailedInformation: {},
...
} |
Versionamento
API interna deve seguir esse padrão, mas é independe do versionamento. Deve estar documentado (tecnica) para as novas.
Validar como passar a versão URL ou header. Testar com o Paulo.
As APIs devem ser versionadas sempre que alguma alteração quebrar o contrato entre o usuário e a plataforma, a versão deve estar presente na URI e deve estar no forma v{numero da versão}. Por exemplo:
| Bloco de código | ||
|---|---|---|
| ||
http://fluig.totvs.com/api/v1/users |
Duas versões da API podem ser suportadas e neste caso deve existir uma politica de depreciação e esta deve estar documentada em um local acessível ao usuário final.
| Informações | ||
|---|---|---|
| ||
A politica de depreciação deve definir principalmente o ciclo de vida da versão da API estipulando um tempo limite em que ela recebera suporte e estara disponível. |
Quando alterar a versão de uma API
O numero da versão indica para o cliente quando alguma alteração pode "quebrar" o código escrito por ele. Deve-se tomar um cuidado especial no processo de versionamento para que o cliente esteja ciente dessas alterações e a frequência com que essas quebras acontecem.
Alterações que devem gerar uma nova versão:
- URIs foram removidas ou renomeadas;
- Foram removidos campos do retorno de um endpoint;
- Foi removido o suporte a um método do endpoint (GET, PUT, POST, etc);
- Um novo parâmetro obrigatório é exigido para o correto funcionamento do endpoint.
Alterações que NÃO devem gerar uma nova versão:
Um novo método é suportado pelo endpoint;- Um novo formato de retorno é suportado pelo endpoint;
- Novas propriedades são retornadas na entidade de retorno do endpoint;
- Novos parâmetros opcionais podem ser passados para o endpoint.
Dicas de como implementar os métodos para tentar manter um padrão de implementação.
Documentação
Todas os métodos, parâmetros, códigos de erro e mensagens de requisição e retorno da API publica devem estar documentadas na página de documentação do fluig. Além disso deve ser gerado um documento SWAGGER com as definições da API.
Visão Geral
Import HTML Content
Conteúdo das Ferramentas
Tarefas