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.
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.