Histórico da Página
Índice
...
O que é uma API?
Âncora | ||||
---|---|---|---|---|
|
Uma Interface de Programação de Aplicações é uma coleção de informações padronizadas estabelecida por um software que possibilita a utilização de suas funcionalidades por outros aplicativos. Com as informações persistidas em uma especificação de API, é possível enviar ou receber dados de uma aplicação sem que seja necessário entrar nos detalhes da implementação deste programa.
...
Para descrever uma API, se faz necessária uma especificação padronizada. O padrão utilizado para a construção das APIs TOTVS é o OpenAPI 3.0, o qual descreve um formato para definição de toda a API. Essa especificação é que define como serão evidenciados os endpoints e seus métodos, parâmetros de operações de entrada e saída, métodos de autenticação, metadados (tais como informações gerais, contato, licença e termos de uso), entre outros.
...
Criação de uma API
Âncora | ||||
---|---|---|---|---|
|
Nesta documentação não entraremos em muitos detalhes sobre a criação dos OpenAPIs, uma vez que as regras para o desenvolvimento de novos arquivos APIs já estão especificadas no nosso Guia de APIs. Uma ótima maneira de iniciar a criação de um novo arquivo OpenAPI é observando como outros documentos foram construídos. Para ter acesso a todas as APIs já desenvolvidas, basta acessar nosso repositório no GitHub.
...
totvsApiTypesBase
Âncora | ||||
---|---|---|---|---|
|
Ao criar uma especificação de API TOTVS, é preciso ter em mente que existem alguns types e parameters padronizados previamente criados pela equipe TTALK, armazenados no arquivo totvsApiTypesBase.json. Com isso, esses parameters não precisam ser implementados "do zero" nos endpoints, mas sim propriamente referenciados na própria especificação de API.
...
Retornar ao Fluxograma de Criação de Integrações
...
Diferenciação entre API e Schema
Âncora | ||||
---|---|---|---|---|
|
Uma API não deve ser confundida com um schema. As APIs são contratos responsáveis por definir os métodos e caminhos que permitem a comunicação entre dois aplicativos. São as APIs que trazem informações relevantes sobre as trocas de dados entre uma aplicação e um produto TOTVS, definindo os moldes das mensagens trafegadas. Já o schema modela a mensagem padronizada propriamente dita. Traz consigo uma forma de apresentar dados e seus tipos, permitindo a posterior transmissão de informações. Definições mais apuradas sobre os schemas podem ser encontradas na documentação sobre as mensagens padronizadas TOTVS.
...
Para uma melhor apresentação visual das APIs, foi criado o portal API Reference, onde todas as APIs desenvolvidas pelos segmentos TOTVS e aprovadas pelo comitê podem ser encontradas.
...
A propriedade "x-totvs"
Âncora | ||||
---|---|---|---|---|
|
A propriedade x-totvs nas APIs está localizada tanto no cabeçalho (tag info) quanto nos métodos dos paths (endpoints) no arquivo OpenAPI, contendo informações diferentes dependendo do local em que está inserida. Contudo, as propriedades x-totvs tem sempre um objetivo em comum: armazenar dados pertinentes aos produtos TOTVS. São nas x-totvs em que são especificadas informações como o nome do produto ao qual se refere, segmento e domínio ao qual está vinculado, adapter atrelado, se determinado verbo está disponível para aquele caminho, entre outros.
...
x-totvs em diferentes partes do OpenAPI
Âncora | ||||
---|---|---|---|---|
|
Abaixo está descrito o comportamento da propriedade x-totvs e o significado de cada uma de suas tags internas, utilizadas apenas no arquivo OpenAPI. Caso sua intenção seja entender o funcionamento do x-totvs no JsonSchema, visite a documentação de Definição da Mensagem no modelo JsonSchema.
- 3.4.1.1
x-totvs dentro da "info"
Âncora xtotvs-info xtotvs-info O exemplo a seguir é um trecho da API UnitOfMeasure v2.API StockGroup
Bloco de código language js title Exemplo collapse true (...) "info": { "description": "API para informações de UnidadeGrupo de MedidaProduto para Unidade de MedidaProdutos TOTVS", "version": "21.000", "title": "UnitOfMeasureGrupo de Produto", "contact": { "name": "T-Talk", "url": "api.totvs.com.br", "email": "[email protected]" }, "x-totvs": { "messageDocumentation": { "name": "UnitOfMeasureStockGroup", "description": "Cadastro de UnidadeGrupo de MedidaProduto", "segment": "Construção e Projetos", "segmentdomain": "ServiçosPlanejamento" }, "productInformation": [ { "product": "Protheus", "contact": "[email protected]", "description": "CadastroGrupo de Unidade de MedidaProduto", "adapter": "QIES030MATS035.prw" }, { "product": "Logix", "contact": "[email protected]", "description": "Cadastro de UnidadeGrupo de MedidaProduto", "adapter": "" } ] } } (...)
A propriedade "messageDocumentation" do x-totvs traz informações sobre a própria API.
- name: título da API;
- description: descrição da API;
- segment: segmento da TOTVS pelo qual aquela API foi implementada.
- domain: domínio de negócio ao qual os recursos pertencem.
- product: produto ao qual aquelas informações do "productInformation" se referem;
- contact: e-mail para contato com quem desenvolveu aquela API naquele determinado produto;
- description: descrição da API para aquele determinado produto;
- adapter: adapter que se comunica com aquela determinada API;
- A propriedade "productInformation" poderia ter ainda a tag helpUrl, que contém um link para a documentação daquela API para aquele produto, caso haja.
Nota title Segment e Product padronizados A grafia dos campos 'segment' e 'product' descritos acima devem estar de acordo com padrões previamente determinados. Para saber qual a grafia correta do segmento e produto que deseja declarar, visite a lista de referências do portal de APIs e verifique no menu lateral os padrões de grafia aceitos.
x-totvs dentro dos verbos dos endpoints
3.4.1.2 x-totvs dentro dos verbos dos endpointsÂncora xtotvs xtotvsÂncora -paths xtotvs-paths O exemplo a seguir também é é um trecho da API UnitOfMeasure v2.
Bloco de código language js title Exemplo collapse true (...) "paths": { "/UnitOfMeasures": { "get": { "tags": [ "UnitOfMeasures" ], "summary": "Retorna lista de Unidade de Medida", "x-totvs": { "productInformation": [ { "product": "Protheus", "available": true, "note": "Este verbo esta disponivel com todos os parametros", "minimalVersion": "12.1.21" }, { "product": "Logix", "available": true, "note": "Este verbo esta disponivel com todos os parametros", "minimalVersion": "12.1.23" } ] } (...)
Diferentemente do x-totvs da "info", a propriedade "messageDocumentation" não está presente nos x-totvs dos "paths".
Já a propriedade "productInformation" traz informações sobre os produtos TOTVS.- product: produto ao qual aquelas informações do "productInformation" se referem;
- available: campo booleano que indicia de o verbo esta implementado no produto;
- note: observações sobre o verbo referente ao produto, como regras específicas;
- minimalVersion: a versão minima na qual o verbo foi implementado no produto.
Sinta-se à vontade para navegar por nossas APIs, tanto pelo API Reference quanto pelo nosso repositório do GitHub, e observar como estão configurados seus respectivos x-totvs!
Clique aqui para retornar ao Fluxograma de Criação de Integrações
...
Aviso | ||
---|---|---|
| ||
O validador automatizado no GitHub avalia a consistência dos 'products' declarados na info e nos paths. Caso um dado produto tenha implementado algum dos endpoints de uma API, ele deve ser declarado no 'productInformation' daquele endpoint e também na 'info'. Analogamente, um dado produto só pode estar declarado na 'info' se tiver implementado pelo menos um dos endpoints daquela API. |
Sinta-se à vontade para navegar por nossas APIs, tanto pelo API Reference quanto pelo nosso repositório do GitHub, e observar como estão configurados seus respectivos x-totvs!
Clique aqui para retornar ao Fluxograma de Criação de Integrações
Identificar se o produto a ser integrado já está definido na documentação da API
Âncora | ||||
---|---|---|---|---|
|
O API Reference é um portal
...
O API Reference é um portal que obtém os dados do JSON da API e os transfere para uma interface visual, tornando a navegação pelas APIs mais atrativa aos usuários. Para identificar quais produtos estão adaptados a uma determinada API, basta acessar o API Reference e identificar quais os produtos que se encontram explicitados (como demonstra a animação abaixo).
...
Clique aqui para retornar ao Fluxograma de Criação de Integrações
...
Editar "x-totvs" da API
Âncora | ||||
---|---|---|---|---|
|
Caso a API já exista, porém não para o produto desejado pelo usuário, significa que há necessidade de adaptar o arquivo OpenAPI para que o produto em questão passe a ser especificado. Para tal, é necessário adicionar ao arquivo JSON da especificação da API novos objetos dentro do array "productInformation" nas propriedades x-totvs, na info e nos verbos dos paths.
Seguindo o mesmo exemplo da API apresentado na seção 3.4.1apresentado nesta seção, a adição de um novo produto se daria da seguinte forma no cabeçalho (info):
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
(...) "info": { "description": "API para informações de UnidadeGrupo de MedidaProduto para Unidade de MedidaProdutos TOTVS", "version": "21.000", "title": "UnitOfMeasureGrupo de Produto", "contact": { "name": "T-Talk", "url": "api.totvs.com.br", "email": "[email protected]" }, "x-totvs": { "messageDocumentation": { "name": "UnitOfMeasureStockGroup", "description": "Cadastro de UnidadeGrupo de MedidaProduto", "segment": "Construção e Projetos", "segmentdomain": "ServiçosPlanejamento" }, "productInformation": [ { "product": "Protheus", "contact": "[email protected]", "description": "CadastroGrupo de Unidade de MedidaProduto", "adapter": "QIES030MATS035.prw" }, { "product": "Logix", "contact": "[email protected]", "description": "Cadastro de UnidadeGrupo de MedidaProduto", "adapter": "" }, { "product": "NovoProdutoTOTVS", "contact": "[email protected]", "description": "Cadastro de UnidadeGrupo de MedidaProduto para NovoProdutoTOTVS", "adapter": "modeloDoAdpter" } ] } } (...) |
...
Clique aqui para retornar ao Fluxograma de Criação de Integrações
...
Versionamento da API
Âncora | ||||
---|---|---|---|---|
|
O versionamento de APIs que atuam sobre entidades com mensagem padronizada seguirá o padrão definido pelo guia de APIs, sendo independente da versão da mensagem padronizada. Entretanto, mudanças no modelo de dados implicam em mudança no contrato da API e, consequentemente, podem exigir alteração da versão da API.
...
- Alterando-se a minorVersion da mensagem padronizada, deve-se alterar a minorVersion da API.
- Alterando-se a majorVersion da mensagem padronizada, deve-se alterar a majorVersion da API.
- Inclusão de verbos HTTP, ações ou filtros na API não alteram versão.
- Alteração de comportamento de endpoint ou na forma de passar os parâmetros alteram versão da API, entretanto não é necessário replicar todos os outros endpoints da API para a nova versão.
...
Exemplos de versionamento
Âncora | ||||
---|---|---|---|---|
|
Para tornar mais claro como versionar as APIs baseadas em mensagem padronizada, colocaremos a seguir um caso de uso.
...
Bloco de código | ||
---|---|---|
| ||
- v1
GET /api/manufacturing/stock/v1/requests
GET /api/manufacturing/stock/v1/requests/{requestId}
POST /api/manufacturing/stock/v1/requests
PUT /api/manufacturing/stock/v1/requests/{requestId}
DELETE /api/manufacturing/stock/v1/requests/{requestId}
POST /api/manufacturing/stock/v1/requests/{requestId}/cancelRequest
- v1.1
GET /api/manufacturing/stock/v1.1/requests
GET /api/manufacturing/stock/v1.1/requests/{requestId}
POST /api/manufacturing/stock/v1.1/requests
PUT /api/manufacturing/stock/v1.1/requests/{requestId}
DELETE /api/manufacturing/stock/v1.1/requests/{requestId}
- v2
POST /api/manufacturing/stock/v2/request/{requestId}/cancelRequest?mandatoryParam=someValue
- v3
GET /api/manufacturing/stock/v3/requests
GET /api/manufacturing/stock/v3/requests/{requestId}
POST /api/manufacturing/stock/v3/requests
PUT /api/manufacturing/stock/v3/requests/{requestId}
DELETE /api/manufacturing/stock/v3/requests/{requestId}
POST /api/manufacturing/stock/v3/request/{requestId}/cancelRequest?mandatoryParam=someValue | ||
Aviso | ||
| ||
/stock/v3/requests
PUT /api/manufacturing/stock/v3/requests/{requestId}
DELETE /api/manufacturing/stock/v3/requests/{requestId}
POST /api/manufacturing/stock/v3/request/{requestId}/cancelRequest?mandatoryParam=someValue |
Aviso | ||
---|---|---|
| ||
Após a reorganização da API pode ser necessário excluir a versão anterior e neste caso, a depreciação deve ser feita conforme politica de cada linha de produto. |
Tipos de Conteúdo
Âncora | ||||
---|---|---|---|---|
|
JSON
Âncora | ||||
---|---|---|---|---|
|
O formato padrão e recomendado de tipo de conteúdo, ou "Content-Type", a ser trafegado via APIs é "application/json".
É representado da seguinte maneira:
Bloco de código | ||
---|---|---|
| ||
"content": {
"application/json": {
"schema": {
"$ref": "https://raw.githubusercontent.com/totvs/ttalk-standard-message/master/jsonschema/schemas/SomeJsonSchema_2_006.json#/definitions/SomeObject"
}
}
} |
XML
Âncora | ||||
---|---|---|---|---|
|
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).
É representado de maneira muito similar ao JSON, porém trocando a notação do ContentType por "application/xml".
Bloco de código | ||
---|---|---|
| ||
"content": {
"application/xml": {
"schema": {
"$ref": "https://raw.githubusercontent.com/totvs/ttalk-standard-message/master/jsonschema/schemas/SomeJsonSchema_2_006.json#/definitions/SomeObject"
}
}
} |
Clique aqui sobre mais detalhes da representação do XML em OAS3
Arquivos Binários
Âncora | ||||
---|---|---|---|---|
|
Para endpoints de arquivos binários, é obrigatório que o schema siga a seguinte estrutura (Com "type": "string" e "format":"binary")
A notação do ContentType é sempre referente ao tipo de arquivo que o mesmo lida. No exemplo abaixo, um endpoint que resolve um arquivo de extensão ".png":
Bloco de código | ||
---|---|---|
| ||
"content": {
"image/png": {
"schema": {
"type":"string",
"format": "binary"
}
}
} |
Clique aqui sobre mais detalhes da representação de arquivos binários em OAS3