Extrair |
---|
25/03/2019 - APIs podem conter domínio de negócio na URL; inclusão do atributo _messages nas mensagens de sucesso (retornos simples e coleções). 03/09/2019 - Exemplo de aplicação de filtro simples em estruturas com entidades aninhadas. |
Índice | ||||||||
---|---|---|---|---|---|---|---|---|
|
...
Nota | ||
---|---|---|
| ||
xaAtenteAtente-se para esta documentação. Para garantir um bom desenvolvimento de APIs publicas ou privadas, é imprescindível que os passos a seguir sejam respeitados. |
...
Exemplo de URLS NÃO amigáveis e que deve ser evitadas
...
Consideramos uma API o agrupamento de endpoints que façam parte da mesma unidade de negócio, criar um novo grupo de endpoints implica em preocupações como versionamento, disponibilidade e documentação. Usamos como base a estrutura "{protocolo}://{host}/{api}/{agrupador}/{dominio}/{versao}/{recurso}". Ex: https://fluig.totvs.com/api/ecm/sucuritysecurity/v1/users. A partir deste ponto deve-se considerar como regra básica a complexidade necessária para descobrir estes endpoints, ou seja, o agrupamento deve facilitar e não complicar a descoberta dos serviços.
...
Informações |
---|
Importante entender a diferença entre o agrupador e o domínio no nome da API. O Agrupadoragrupador, é geralmente definido o segmento de atuação da API, é uma maneira de facilitar a localização das API, EX.: Financeiro, Contábil. Já o domínio é uma subdivisão especifica de determinado módulo, criando assim o escopo de uma determinada API, separando somente seus endpoints, facilitando o uso de ferramentas de gerenciamento de API EX.: Financeiro/ContasPagar, Financeiro/ContasReceber, Contábil/Lançamentos, Contábil/Balanço. |
Informações |
---|
APIs escritas utilizando o protocolo de mensagem padronizada não devem definir o nome do produto na URL. A ideia de APIs padronizadas é que a mesma assinatura atenda diferentes produtos. A assinatura de API padronizada segue a nomenclatura abaixo: "{protocolo}://{host}/{api}/{agrupador}/{dominio}/{versao}/{recurso}" |
Estrutura OAS (Open Api Specification 3.0.1):
Bloco de código | ||
---|---|---|
| ||
openapi: 3.0.1 info: title: Estrutura de Url para API's description: 'Consideramos uma API o agrupamento de endpoints que façam parte da mesma unidade de negócio. Usamos como base a estrutura "{protocolo}://{host}/{api}/{produto}/{agrupador}/{dominio}/{versao}/{recurso}"' version: '1.0' externalDocs: url: 'http://tdn.totvs.com/display/INT/Guia+de+implementacao+das+APIs+TOTVS' servers: - url: '{protocolo}://{host}/{api}/{produto}/{agrupador}/{dominio}/{versao}/{recurso}' variables: protocolo: default: https enum: - http - https host: default: host api: default: api produtoagrupador: default: produtoagrupador agrupadordominio: default: agrupadordominio versao: default: versao recurso: default: recurso paths: {} components: {} |
...
Todos os endpoints de coleção devem suportar ordenação. A definição de como a lista deve ser ordenada é definida no parâmetro de urlquery order respeitando as seguintes regras:
...
As coleções podem suportar filtro e devedevem usar as técnicas abaixo de acordo com a complexidade exigida pela função:
...
Filtros simples devem usar parâmetros de query no formato propriedade=filtrovalor e as propriedades suportadas e como elas , bem como a forma como serão interpretadas, devem estar listadas na documentação do endpoint. Ex:
Bloco de código | ||
---|---|---|
| ||
GET https://totvs.com.br/api/fluig/fdn/v1/users?name=john&surname=doe |
Filtros complexos e que forneçam uma linguagem de filtro devem seguir o padrão definido para os filtros no documento ODATA na versão 4. (opcional)
Exemplo de filtros no padrão odata:
Opcionalmente, em endpoints que tenham estrutura com entidades aninhadas, a propriedade usada para filtrar os resultados deve usar o formato propriedade_pai.propriedade_filho.
Não há limite para os níveis que se pode referenciar, mas deve-se levar em consideração o quão complexa pode ser a implementação. Quando houver limitação quanto a quantidade de níveis referenciados, importante documentar na API.
Exemplo de uso do filtro com propriedades aninhadas:
Bloco de código | ||
---|---|---|
| ||
GET https://totvs.com.br/api/fluig/fdn/v1/users?communities.name="Vendas" |
No exemplo acima, serão retornados todos os usuários (users) cuja propriedade name (que está contida na propriedade communities da entidade users) seja igual a "Vendas".
Filtros complexos e que forneçam uma linguagem de filtro devem seguir o padrão definido para os filtros no documento ODATA na versão 4.
Exemplo de filtros no padrão odata:
Operator | Description | Example |
Logical Operators | ||
eq | Equal | /Suppliers?$filter=Address/City eq 'Redmond' |
ne | Not equal | /Suppliers?$filter=Address/City ne 'London' |
gt | Greater than | /Products?$filter=Price gt 20 |
ge | Greater than or equal | /Products?$filter=Price ge 10 |
lt | Less than | /Products?$filter=Price lt 20 |
le | Less than or equal | /Products?$filter=Price le 100 |
and | Logical and | /Products?$filter=Price le |
Operator | Description | Example |
Logical Operators | ||
eq | Equal | /Suppliers?$filter=Address/City eq 'Redmond' |
ne | Not equal | /Suppliers?$filter=Address/City ne 'London' |
gt | Greater than | /Products?$filter=Price gt 20 |
ge | Greater than or equal | /Products?$filter=Price ge 10 |
lt | Less than | /Products?$filter=Price lt 20 |
le | Less than or equal | /Products?$filter=Price le 100 |
and | Logical and | /Products?$filter=Price le 200 and Price gt 3.5 |
or | Logical or | /Products?$filter=Price le 3.5 or Price gt 200 |
not | Logical negation | /Products?$filter=not endswith(Description,'milk') |
Grouping Operators | ||
( ) | grouping | /Products?$filter=(Price lt 5) |
Opcionalmente, a api pode disponibilizar o filtro especial "datemodified" para retornar registros alterados a partir de uma determinada data. Ex:
O valor desse filtro deve seguir o definido em Formatos de data.
Exemplo:
Bloco de códigocode | ||
---|---|---|
| ||
GET https://totvs.com.br/api/fluig/fdn/v1/users?datemodified='2018-01-01' |
...
Bloco de código | ||
---|---|---|
| ||
GET https://totvs.com.br/api/fluig/fdn/v1/users?$filter=datemodified ge '2018-01-01' and datemodified le '2018-01-31' |
Todos os endpoints de coleção devem suportar paginação. A definição de como a coleção deve ser paginada é definida pelos parâmetros de url page e pageSize respeitando as seguintes regras:
...
...
Método | Descrição | Idempotente | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
GET | Retorna o valor corrente do objeto. | Sim | ||||||||||
PUT | Sobrescreve o objeto quando aplicável. Por exemplo: O cliente gostaria de sobrescrever o usuário com novos valores:
| Sim | ||||||||||
DELETE | Exclui o objeto. | Sim | ||||||||||
POST | Cria um novo objeto ou submete um comando ao objeto. | Não | ||||||||||
HEAD | Retorna os metadados da requisição em casos em que o cliente não precisa do corpo das requisições do tipo GET. | Sim | ||||||||||
PATCH | Também usado para atualizar uma entidade, mas diferente do PUT, recebe em seu corpo uma série de instruções ou o estado no qual o cliente gostaria que a entidade estivesse no final da operação. Deve ser tratado de forma atômica, ou seja, ou todas as instruções foram completadas com sucesso ou deve retornar erro ao cliente. PATH pode causar efeitos colaterais e portanto não é considerado seguro ou idempotente.
O servidor deverá implementar o serviço de modo que apenas o nome do usuário seja atualizado e todas as outras propriedades sejam mantidas. | Não | ||||||||||
OPTIONS | Deve retornar pelo menos o campo Allow no cabeçalho da resposta listando os verbos suportados pelo endpoint. | Sim |
...
Métodos DELETE, GET, HEAD e OPTIONS não deve ser utilizado corpo na mensagem e sim utilizar query string .
Em métodos POST evitar a utilização de path param e utilizar corpo na mensagem a fim de manter as boas práticas de desenvolvimento.
...
JSON deve ser o formato padrão para mensagens mensagens de resposta. Apenas nos casos onde se justificar, outro tipo de mídia pode ser usado. Por exemplo, numa API que retorne uma imagem ou um documento PDF.
Tipos de dados JSON
Os tipos de dados e a notação para os campos da mensagem JSON deve seguir os padrões descritos no documento ECMA-404.
...
Bloco de código | ||
---|---|---|
| ||
GET http://totvs.com.br/api/fluig/fdn/v1/users/110 { name _expandables: "John"["permissions","communities","detailedInformation"], surname: "Doe" } |
...
Nos casos em que o resultado da operação do endpoint represente uma coleção, os itens devem estar agrupados em um objeto com as propriedades hasNext, indicando se existe uma próxima página com mais registros para aquela coleção e items que representam a lista de itens retornados.
Bloco de código | ||
---|---|---|
| ||
{ hasNext: true, items: [ {} id: 10, name: "John", surname: "Doe", {}age: 25, ... ] }country: "US" } |
Opcionalmente, o atributo _messages pode ser incluído no objeto retornado para fornecer alguma informação complementar ao processamento realizado (mensagens de aviso, de negócio, etc.). O formato do objeto de mensagem segue o padrão anteriormente descrito, para mensagens de erro.A estrutura acima é a mínima esperada para respostas de coleção. Entretanto, pode-se retornar mais campos se for necessário desde que a estrutura básica se mantenha. Por exemplo:
Bloco de código | ||
---|---|---|
| ||
{
totvs_transaction_id: 1,
total: 100,
hasNext: true,
items: [
{},
{},
...
]
} |
Observe que na estrutura acima, os atributos totvs_transaction_id e total foram adicionados ao objeto de resposta, enquanto os atributos hasNext e items foram mantidos.
Por padrão, nas mensagens de DELETE, a resposta deve ser enviada com HTTP Code 204 (No content) e sem corpo no retorno.
Caso a regra de negócio necessitar de um retorno com conteúdo, este deve vir com HTTP Code 200 (OK) e com a entidade excluída sem expandir os sub-níveis.
...
GET http://totvs.com.br/api/fluig/fdn/v1/users/10
{
_expandables: ["permissions","communities","detailedInformation"],
id: 10,
name: "John",
surname: "Doe",
age: 25,
country: "US"
_messages: [{
code: "INFO",
message: "Esta é uma mensagem informativa",
detailedMessage: "Mais detalhes sobre esta mensagem podem ser vistos aqui."
}]
} |
Âncora | ||||
---|---|---|---|---|
|
Nos casos em que o resultado da operação do endpoint represente uma coleção, os itens devem estar agrupados em um objeto com as propriedades hasNext, indicando se existe uma próxima página com mais registros para aquela coleção e items que representam a lista de itens retornados.
Bloco de código | ||
---|---|---|
| ||
{
hasNext: true,
items: [
{},
{},
...
]
} |
Para o retorno de coleções, também é possível incluir o atributo _messages, conforme segue:
Bloco de código | ||
---|---|---|
| ||
{
hasNext: true,
items: [
{},
{},
...
],
_messages: [{
code: "INFO",
message: "Uma mensagem informativa.",
detailedMessage: "Detalhes relativos a mensagem."
}]
} |
A estrutura acima é a mínima esperada para respostas de coleção. Entretanto, pode-se retornar mais campos se for necessário desde que a estrutura básica se mantenha. Por exemplo:
Bloco de código | ||
---|---|---|
| ||
{
totvs_transaction_id: 1,
total: 100,
hasNext: true,
items: [
{},
{},
...
]
} |
Observe que na estrutura acima, os atributos totvs_transaction_id e total foram adicionados ao objeto de resposta, enquanto os atributos hasNext e items foram mantidos.
Por padrão, nas mensagens de DELETE, a resposta deve ser enviada com HTTP Code 204 (No content) e sem corpo no retorno.
Caso a regra de negócio necessitar de um retorno com conteúdo, este deve vir com HTTP Code 200 (OK) e com a entidade excluída sem expandir os sub-níveis.
Âncora | ||||
---|---|---|---|---|
|
Dividimos os erros em duas categorias: Erros de negócio ou requisição e Erros não esperados.
Erros de negócio ou requisição
São aqueles causados por dados inválidos nas requisições ou intencionalmente lançados do endpoint para o cliente. Todos os erros deste tipo devem obrigatoriamente retornar um código HTTP da família 4xx
Dividimos os erros em duas categorias: Erros de negócio ou requisição e Erros não esperados.
Erros de negócio ou requisição
São aqueles causados por dados inválidos nas requisições ou intencionalmente lançados do endpoint para o cliente. Todos os erros deste tipo devem obrigatoriamente retornar um código HTTP da família 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 as permissões necessárias 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 erro 400 - Bad Request;
O cliente chamou o endpoint passando no cabeçalho que aceita como retorno xml (Content-Type: text/xml) mas o serviço só consegue retornar JSON. Deve retornar o erro HTTP 406 - Not Acceptable.
O cliente chamou o endpoint para criar um usuário mas já existe um usuário com o mesmo código. Deve ser retornado o código de erro 409 - Conflict
Erros não esperados
São os erros não tratados ou não intencionais. Esse tipo de erro deve sempre retornar códigos HTTP da família 5xx. Ex:
O cliente chamou um endpoint mas o servidor não pode responder por que estava sobrecarregadoestava devidamente autenticado. Deve retornar ser retornado o código 503 401 - Service UnavailableUnauthorized;
O cliente chamou um endpoint para subir um documento mas não havia espaço em disco no servidormas mesmo estando autenticado não possui as permissões necessárias para efetuar a operação. Deve retornar o código 507 - Insufficiente Storage.
A APIs devem permitir que o cliente filtre os campos retornados nas entidades. Para isso ele deve passar o parâmetro de query com nome fields, que consiste de uma lista com o nome das propriedades JSON que serão retornadas. Os campos omitizados serão removidos do retorno (mesmo que o cliente tenha solicitado expandi-los).
Omitir o campo fields fara com que todos os campos sejam retornados.
Por exemplo, o cliente faz uma requisição para retornar os dados do cliente com id 10:
Bloco de código | ||
---|---|---|
| ||
GET http://totvs.com.br/api/fluig/fdn/v1/users/10
{
_expandables: ["Permissions"],
name: "John",
surname: "Doe",
age: 18,
country: US
} |
Caso os únicos campos interessantes para o cliente sejam o "name" e "age" ele pode reduzir a quantidade de dados usando o parâmetro fields. Ex:
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 erro 400 - Bad Request;
O cliente chamou o endpoint passando no cabeçalho que aceita como retorno xml (Content-Type: text/xml) mas o serviço só consegue retornar JSON. Deve retornar o erro HTTP 406 - Not Acceptable.
O cliente chamou o endpoint para criar um usuário mas já existe um usuário com o mesmo código. Deve ser retornado o código de erro 409 - Conflict
Erros não esperados
São os erros não tratados ou não intencionais. Esse tipo de erro deve sempre retornar códigos HTTP da família 5xx. Ex:
O cliente chamou um endpoint mas o servidor não pode responder por que estava sobrecarregado. Deve retornar o código 503 - Service Unavailable;
O cliente chamou um endpoint para subir um documento mas não havia espaço em disco no servidor. Deve retornar o código 507 - Insufficiente Storage.
A APIs devem permitir que o cliente filtre os campos retornados nas entidades. Para isso ele deve passar o parâmetro de query com nome fields, que consiste de uma lista com o nome das propriedades JSON que serão retornadas. Os campos omitizados serão removidos do retorno (mesmo que o cliente tenha solicitado expandi-los).
Omitir o campo fields fara com que todos os campos sejam retornados.
Por exemplo, o cliente faz uma requisição para retornar os dados do cliente com id 10:
Bloco de código | ||
---|---|---|
| ||
GET http://totvs.com. | ||
Bloco de código | ||
| ||
GET http://totvs.com.br/api/fluig/fdn/v1/users/10?fields=name,age { name: " _expandables: ["permissions","communities","detailedInformation"], id: 10, name: "John", surname: "Doe", age: 18 }25, country: "US" } |
Caso os únicos campos interessantes para o cliente sejam o "name" e "age" ele pode reduzir a quantidade de dados usando o parâmetro fields. Ex:
Bloco de código | ||
---|---|---|
| ||
GET http://totvs.com.br/api/fluig/fdn/v1/users/10?fields=name,age
{
name: "John",
age: 25
} |
Informações |
---|
O parâmetro fields deve ter precedência sobre o parâmetro |
Informações |
O parâmetro fields deve ter precedência sobre o parâmetro expand. Isso que dizer que o campo não será retornado a menos que esteja na lista de campos do parâmetro fields mesmo que ele esteja presente na lista de campos a serem expandidos do parâmetro expand. |
...
Bloco de código | ||
---|---|---|
| ||
GET https://totvs.com/api/fluig/fdn/v1/users/10 { _expandables: ["permissions", "communities", "detailedInformation"], id: 10, name: "UsuárioJohn", surname: "Doe", age: 25, country: "US" } |
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.
...
Bloco de código | ||
---|---|---|
| ||
GET https://totvs.com/api/fluig/fdn/v1/users/10?expand=communities { _expandables: ["permissions", "communities","detailedInformation"] # refere-se aos atributos do objeto pai (1o nível), id: 10, name: "UsuárioJohn", surname: "Doe", age: 25, country: "US", communities: [{ _expandables: ["permissions"], { # refere-se ao _expandables: ["Permissions"], # refere-se ao atributo permissions deste objeto-filhoatributo permissions de communities (2o nivel) name: "Vendas", photoUrl: "https://totvs.com/communities/1/photo" }, { _expandables: ["permissions"], # refere-se ao atributo permissions destede objeto-filho communities name: "Outra comunidade", photoUrl: photoUrl: "https://totvs.com/communities/2/photo" } ] } |
Note que as propriedades do objeto expandido não são retornadas 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://totvs.com/api/fluig/fdn/v1/users/10?expand=communities.permissions { _expandables: ["permissions", "communities","detailedInformation"], id: 10, name: "UsuárioJohn", surname: "Doe", age: 25, country: "US", communities: [{ name: "Vendas", photoUrl: "https://totvs.com/communities/1/photo", permissions: { isAdmin: true, canView: true } }, { }, { namename: "Outra comunidade", photoUrl: "https://totvs.com/communities/2/photo", permissions: { isAdmin: true, canView: true } }] } |
Informações | ||
---|---|---|
| ||
A API deve suportar a expansão de até dois níveis de propriedade de retorno, ex: prop1.prop2.prop3. Nos casos em que o objeto tenha uma sub coleção é recomendável que o número máximo de registros dessa coleção não ultrapasse 20 registros. Se houver a necessidade de retornar mais itens, considerar criar um endpoint especifico para retornar a coleção com suporte a filtro, ordenação, etc. |
...
Ao realizar um POST, PUT ou DELETE em um recurso que executa seu processamento de maneira assíncrona, o mesmo DEVE retornar o código 202 Accepted, com cabeçalho location apontando para um recurso temporário que permita o acompanhamento do status da requisição.
Informações | ||
---|---|---|
| ||
A implementação do modelo assíncrono não é obrigatório. A opção por este modelo deve basear no tempo e recurso necessário para o processamento de uma requisição. |
Ao realizar o GET no recurso temporário, enquanto ainda estiver sendo processado, o mesmo DEVE retornar o código 200 e um JSON com a propriedade status definida como “pending”. Esse retorno PODE, e é uma boa prática, retornar a propriedade progress, informando o percentual de conclusão da operação solicitada.
...
Para cancelar a execução do processamento, quando permitido, o client deve executar DELETE no recurso temporário.
Ao acessar o recurso temporário que finalizou seu processamento com erros, retorna o erro adequado, conforme definido em Mensagens de Erro e Código 4xx versus 5xx
Ao acessar o recurso temporário que finalizou seu processamento com sucesso, o mesmo DEVE retornar o código 303 (See Other) com o cabeçalho Location, apontando para endereço do real recurso criado.
A deleção do recurso temporário não é obrigatória e PODE ser feita através de DELETE do client, ou através do próprio server, após um tempo determinado para expirá-lo. Nesse segundo caso, ao tentar acessá-lo DEVE retornar 410 (Gone).
...
Esse estilo de arquitetura permite usar links no conteúdo da resposta para que o cliente possa navegar dinamicamente para o recurso apropriado. Isso é conceitualmente o mesmo que um usuário da Web navegando pelas páginas e clicando nos hiperlinks apropriados para atingir uma meta final.
O padrão HATEOAS deve ser utilizado no retorno de entidades relacionadas a principal e que não são parte do recurso princiapalprincipal. Ex.
Bloco de código | ||
---|---|---|
| ||
GET https://totvs.com/api/fluig/fdn/v1/users/10 { _expandables: ["permissions","communities","detailedInformation"], "id" : 10, name: "John", "name" surname: "UsuárioDoe", age: 25, "age" country: 25, "US", "links": [ { "rel": "communities", "href": "/fdn/v1/communities/5" }, { "rel": "permissions", "href": "/fdn/v1/permissions/30" } ] } |
...
O formato padrão e recomendado de tipo de conteúdo, ou "Content-Type", a ser trafegado via APIs é "application/json".
Em alguns casos pode existir a necessidade de utilizar "application/xml" , por ex: quando é exigido por legislação. Nessa situação, as mesmas regras definidas nos tópicos anteriores continuam valendo, visto que estas estão relacionadas ao schema. (Se possível, evitar esse uso e sempre priorizar o JSON)
Outro cenário é o download e upload de arquivos binários: Não utilizamos os tipos "multipart/xxxx", e sim os mais específicos ao tipo do arquivo.
Exemplos:
"image/png" para o download ou upload de um arquivo com extensão ".png".
Clique aqui para lista completa dos tipos permitidos
Informações | ||
---|---|---|
| ||
Utilizar o cabeçalho "Content-Disposition"="attachment" na resposta de uma API faz com que o navegador faça o download do arquivo ao invés de renderizar o seu conteúdo |
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 major indica uma grande versão da API, ou seja, a API mudou significativamente em seu formato e comportamento.
A versão minor indica uma alteração que pode quebrar o código do cliente.
Por exemplo:
Bloco de código | ||
---|---|---|
| ||
http://totvs.com/api/fluig/fdn/v1/users
http://totvs.com/api/fluig/fdn/v1.5/users
http://totvs.com/api/fluig/fdn/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 o ciclo de vida da versão da API estipulando um tempo limite em que ela receberá suporte e 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. |
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 elas acontecem usando algum tipo de release notes ou documentação.
Bloco de código | ||
---|---|---|
| ||
http://totvs.com/api/fluig/fdn/v1/users
http://totvs.com/api/fluig/fdn/v1.5/users
http://totvs.com/api/fluig/fdn/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 o ciclo de vida da versão da API estipulando um tempo limite em que ela receberá suporte e 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. |
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 elas acontecem usando algum tipo de release notes ou 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. Além disso deve ser gerado um documento OpenAPI com as definições da API.
...