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.
É de grande interesse para a TOTVS que aplicações externas consigam se comunicar com seus produtos de maneira facilitada. Por meio da implementação de uma API, é possível que outras aplicações obtenham dados internos dos produtos TOTVS, apenas enviando uma requisição HTTP para o endereço devidamente descrito na especificação da API.
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.
<Tópico pendente de informação>
As regras para o desenvolvimento de APIs 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.
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.
Anteriormente era possível que o schema fosse incluso diretamente na API, porém essa regra foi modificada. Para aprimorar a reusabilidade dos schemas, agora os arquivos JSON devem ser separados em API e JsonSchema. Esse modelo possibilita a utilização do protocolo transactions sem que haja a necessidade do desenvolvimento de uma API, caso essa configuração seja suficiente para suprir a necessidade e interesse do desenvolvedor. Como vantagem adicional, uma mesma API pode ser utilizada de formas diferentes, alterando somente o schema o qual ela faz referência.
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.
<Tópico pendente de informação>
A propriedade x-totvs nas APIs traz diferentes informações dependendo da seção em que ela está localizada no OpenAPI, porém com um objetivo em comum: armazenar dados pertinentes aos produtos TOTVS. São nas propriedades x-totvs ao longo do documento que são especificadas informações como: nome do produto ao qual se refere, segmento ao qual está vinculado, adapter atrelado, se determinado verbo está disponível, entre outros.
A propriedade x-totvs pode estar presente em diferentes seções do OpenAPI
Implementação de APIs com Mensagem Padronizada
O exemplo a seguir é um trecho da API UnitOfMeasure v2.
(...)
"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.
Já a propriedade "productInformation" traz informações sobre os produtos TOTVS.
O exemplo a seguir também é um trecho da API UnitOfMeasure v2.
|
Diferentemente dos 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.
<Tópico pendente de informação>
O API reference tira os dados do json da api. Ir no api reference e identificar se o produto ta la, dentro dos x-totvs
<Tópico pendente de informação>
Caso a api já exista mas não para seu produto, significa que você precisa aadaptar a API ao seu produto.
Adicionar novo produto, especificação de adapters etc etc