Histórico da Página
Índice
3.1 O que é uma API?
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.
3.2 Criação de uma API
<Tópico pendente de informação>
As As regras para o desenvolvimento de especificações de APIs novos arquivos OpenAPIs estão especificadas no nosso Guia de Implementação de APIs.
Explicaremos mais o x-totvs. Mais detalhes sobre construção de APIs podem ser encontrados em Implementação de APIs com Mensagem Padronizada#Defini%C3%A7%C3%A3odaAPIeseusEndpoints
Todas as APIs já desenvolvidas podem ser encontradas em nosso repositório do GitHub..
3.2.1 totvsApiTypesBase
Ao criar uma especificação de API TOTVS, é necessário ter em mente que existem alguns métodos padrão previamente criados pela TTALK.
Com isso, esses endpoints não precisam ser implementados, apenas propriamente referenciados.Falar sobre apiTotvsBase
Retornar ao Fluxograma de Criação de Integrações
3.3 Diferenciação entre API e Schema
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 pontos. 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 é 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.
3.4 A propriedade "x-totvs"
<Tópico pendente de informação>
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 ao qual está vinculado, adapter atrelado, se determinado verbo está disponível para aquele caminho, entre outros.
3.4.1 x-totvs em diferentes partes do OpenAPI
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 a 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"
O exemplo a seguir é um trecho da API UnitOfMeasure v2.
Bloco de código language js title Exemplo collapse true (...) "info": { "description": "API para informações de Unidade de Medida para Unidade de Medida TOTVS", "version": "2.000", "title": "UnitOfMeasure", "contact": { "name": "T-Talk", "url": "api.totvs.com.br", "email": "[email protected]" }, "x-totvs": { "messageDocumentation": { "name": "UnitOfMeasure", "description": "Cadastro de Unidade de Medida", "segment": "Serviços" }, "productInformation": [ { "product": "Protheus", "contact": "[email protected]", "description": "Cadastro de Unidade de Medida", "adapter": "QIES030.prw" }, { "product": "Logix", "contact": "[email protected]", "description": "Cadastro de Unidade de Medida", "adapter": "" } ] } } (...)A propriedade "messageDocumentation" do x-totvs traz informações sobre a própria API.
...
- 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.
3.4.1.2 x-totvs dentro dos verbos dos
"paths"endpoints
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.
...
Clique aqui para retornar ao Fluxograma de Criação de Integrações
3.4.2 Identificar se o produto a ser integrado já está definido na documentação da API
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
3.4.3 Editar "x-totvs" da API
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 os exemplos apresentados anteriormentena seção 3.4.1, 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 Unidade de Medida para Unidade de Medida TOTVS",
"version": "2.000",
"title": "UnitOfMeasure",
"contact": {
"name": "T-Talk",
"url": "api.totvs.com.br",
"email": "[email protected]"
},
"x-totvs": {
"messageDocumentation": {
"name": "UnitOfMeasure",
"description": "Cadastro de Unidade de Medida",
"segment": "Serviços"
},
"productInformation": [
{
"product": "Protheus",
"contact": "[email protected]",
"description": "Cadastro de Unidade de Medida",
"adapter": "QIES030.prw"
},
{
"product": "Logix",
"contact": "[email protected]",
"description": "Cadastro de Unidade de Medida",
"adapter": ""
},
{
"product": "NovoProdutoTOTVS",
"contact": "[email protected]",
"description": "Cadastro de Unidade de Medida para NovoProdutoTOTVS",
"adapter": "modeloDoAdpter"
}
]
}
}
(...)
|
Já para adição nos paths, o novo produto deve ser adicionado em cada um dos caminhos e verbos em que há cobertura pelo adapter. O exemplo para adição em apenas um verbo em um path pode ser visualizado abaixo:
| Bloco de código | ||||||
|---|---|---|---|---|---|---|
| ||||||
(...)
"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"
},
{
"product": "NovoProdutoTOTVS",
"available": true,
"note": "Alguma nota caso seja necessário",
"minimalVersion": "12.1.23"
}
]
}
(...) |
...
Import HTML Content
Visão Geral
Conteúdo das Ferramentas