Histórico da Página
...
| Bloco de código | ||
|---|---|---|
| ||
GET https://fluig.totvs.com/api/users/10 { data: { _expandables: ["permissions", "communities", "detailedInformation"], id: 10, name: "Usuário", age: 25, permissions: [], communities: [], detailedInformation: {}, ... } |
Caso o cliente queira expandir as propriedades, ele deve então fazer uma requisição informando o parâmetro expand na url e passando como valor uma lista separada por virgula (,) dos campos exatamente como descritos no campo _expandables.
| Nota | ||
|---|---|---|
| ||
Apenas o primeiro nível das propriedades deve ser expandido, ou seja, se o objeto expandido tiver propriedades expansíveis elas devem vir retraídas. |
Por exemplo, no cenário em que o cliente gostaria de expandir as comunidades da entidade usuário:
_expandables: ["permissions"],
name: "Vendas",
photoUrl: "https://fluig.totvs.com/communities/1/photo",
permissions: {}
},
{
_expandables: ["permissions"],
name: "Outra comunidade",
photoUrl: "https://fluig.totvs.com/communities/2/photo",
permissions: {}
}
]
detailedInformation: { }
}
} |
Caso o cliente queira expandir as propriedades, ele deve então fazer uma requisição informando o parâmetro expand na url e passando como valor uma lista separada por virgula (,) dos campos exatamente como descritos no campo _expandables.
| Nota | ||
|---|---|---|
| ||
Apenas o primeiro nível das propriedades deve ser expandido, ou seja, se o objeto expandido tiver propriedades expansíveis elas devem vir retraídas. |
Por exemplo, no cenário em que o cliente gostaria de expandir as comunidades da entidade usuário:
| Bloco de código | ||
|---|---|---|
| ||
GET https://fluig.totvs.com/api/users/10?expand=communities
{
data: {
_expandables: ["permissions", "detailedInformation"]
id: 10
name: "Usuário"
age: 25
permissions: []
communities: [
{
_expandables: ["permissions"],
name: "Vendas",
photoUrl: "https://fluig.totvs.com/communities/1/photo",
permissions: {}
},
{
_expandables: ["permissions"],
name: "Outra comunidade",
photoUrl: " | ||
| Bloco de código | ||
| ||
GET https://fluig.totvs.com/apicommunities/users/10?expand=communities { _expandables: ["permissions", "detailedInformation"], id: 10, name: "Usuário", age: 25, permissions: [], communities: [{ _expandables: [permissions], name: "Vendas", photoUrl:2/photo", permissions: {} } ] detailedInformation: { } } } |
Note que as propriedades do objeto expandido devem vir retraídas por padrão. O cliente pode solicitar que as propriedades dos objetos sejam expandidas separando as sub-propriedades com ponto (.). Usando o exemplo acima, o usuário gostaria de expandir as permissões das comunidades da entidade usuário:
| Bloco de código | ||
|---|---|---|
| ||
GET "https://fluig.totvs.com/communitiesapi/1/photo",users/10?expand=communities.permissions { permissionsdata: {} }, { _expandables: ["permissions],", "detailedInformation"] id: 10 name: "Outra comunidadeUsuário", photoUrlage: "https://fluig.totvs.com/communities/2/photo", 25 permissions: [] permissionscommunities: {}[{ }], detailedInformationname: {}, ... } |
Note que as propriedades do objeto expandido devem vir retraídas por padrão. O cliente pode solicitar que as propriedades dos objetos sejam expandidas separando as sub-propriedades com ponto (.). Usando o exemplo acima, o usuário gostaria de expandir as permissões das comunidades da entidade usuário:
| Bloco de código | ||
|---|---|---|
| ||
GET "Vendas", photoUrl: "https://fluig.totvs.com/apicommunities/users/10?expand=communities.permissions { _expandables: ["permissions", "detailedInformation"], id: 10, name: "Usuário", age: 25, permissions: [], communities: [{ 1/photo", permissions: { isAdmin: true, canView: true } }, { name: "VendasOutra comunidade", photoUrl: "https://fluig.totvs.com/communities/12/photo", permissions: { isAdminpermissions: true,{ canView: true } isAdmin: }true, { name: "Outra comunidade", photoUrl: "https://fluig.totvs.com/communities/2/photo", permissionscanView: {true isAdmin: true, canView: true} } }], detailedInformation: { }, ...} } |
Versionamento
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{major.minor}.
...
A versão minor indica uma alteração que pode quebrar o código do cliente.
Por exemplo:
| Bloco de código | ||
|---|---|---|
| ||
http://fluig.totvs.com/api/v1/users http://fluig.totvs.com/api/v1.5/users http://fluig.totvs.com/api/v2/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 estará disponível. A politica é pode ser única para cada área de negócio mas deve estar documentada e evidente para o usuário final. |
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 acontecemelas acontecem usando algum tipo de release notes ou documentação.
Alterações que devem gerar uma nova versão "minor":
- 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;
- Um novo endpoint foi adicionado a API.
Alterações que NÃO devem gerar uma nova versão "minor":
- 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.
...
Visão Geral
Import HTML Content
Conteúdo das Ferramentas
Tarefas