Nomenclatura: Global, Contas (Accounts) e Consumers (Chaves de API)

A definição e estabelecimento de Globals, Contas (Accounts), Consumers (Chaves de API) fazem parte do setup da Digibee Integration Platform e praticamente todos os fluxos farão uso de uma ou mais dessas configurações durante sua execução.

Boas práticas de nomenclatura

• Combine prefixos claros para identificar o propósito e contexto de cada elemento.

• Utilize letras minúsculas.

• Separe as palavras usando hífen (-).

• É de extrema importância que definições estejam bem classificadas e nomeadas para evitar duplicidades, sobreposição e até uso indevido dentro dos fluxos.

Globals

Na nomenclatura de Globals é recomendado o uso de três parâmetros para compor o nome:

[categoria]-[sistema]-[tecnologia]

Categoria

• URL

• host

• systemid

Sistema

• SAP

• VTEX

• ServiceNow

• Oracle

• Protheus

Tecnologia

• REST

• SOAP

• JDBC

• RFX

Uma vez identificados todos os parâmetros da integração, podemos compor o nome da Global, como nos exemplos abaixo:

• url-vtex-rest

• host-sap-rfc

• url-sap-soap

• systemid-sap-rfc

• url-servicenow-rest

• host-oracle-jdbc

Leia a documentação para conhecer o passo a passo para criar uma Global.

Cenário de exemplo

Neste cenário, é necessário realizar uma integração com um endpoint REST com as seguintes URLs:

• Ambiente de teste: https://test.godigibee.io/pipeline/demo/v1/api-extrato-custom-demo
• Ambiente de produção: https://api.godigibee.io/pipeline/demo[/v1/api-extrato-custom-demo](https://test.godigibee.io/pipeline/demo/v1/api-extrato-custom-demo)

O host do serviço está localizado no trecho: https://test.godigibee.io ou https://api.godigibee.io.

O restante https://test.godigibee.io/pipeline/demo/v1/api-extrato-custom-demo é o path referente apenas ao serviço que vai ser usado nessa integração.

• Apenas o primeiro trecho deve ser cadastrado na Global.

• O restante deve ser utilizado diretamente no pipeline. Ou seja, deve ser criada outra global para armazenar o path, principalmente em casos onde o path muda de acordo com o ambiente a ser executado.

Contas (Accounts)

Assim como no cadastro das Globals, é usado o mesmo raciocínio para catalogar e padronizar a nomenclatura das Contas (Accounts), com a mesma abordagem para definição de prefixos. A recomendação é organizar as Contas (Accounts) com base em três parâmetros:

[sistema]-[tecnologia]-[tipo]

Abaixo alguns dos casos de uso mais comuns em integrações:

Sistema

• SQLServer

• portalabc

• SAP

Tecnologia

• REST

• JDBC

• RFC

Tipo

• clientdid

• clientsecret

• basic

Uma vez identificados todos os parâmetros da integração, é possível compor o nome da Conta (Account), como nos exemplos abaixo:

• portalabc-rest-clientid

• portalabc-rest-clientsecret

• sqlserver-jdbc-basic

• sap-rfc-basic

• sap-jdbc-clientid

Para entender como configurar cada tipo de conta, acesse a documentação de Contas (Accounts).

Consumers (Chaves de API)

Assim nos cadastros das anteriores, foi adotado mesmo raciocínio para catalogar e padronizar a nomenclatura de Consumers (Chaves de API), com a mesma abordagem para definição de prefixos.

A recomendação é organizar a nomenclatura com base em dois parâmetros:

[sistemaConsumer]-[unidadeDeNegocio / fornecedor]

Abaixo alguns dos casos de uso mais comuns em integrações:

Sistema

• SAP

• Protheus

• Servicenow

• Datadog

Unidade de negócio / Fornecedor

• RH

• TI

• Fornecedor A

• Fornecedor B

Uma vez identificados todos os parâmetros da integração, é possível compor o nome dos Consumers (Chaves de API), como nos exemplos abaixo:

• sap-rh

• servicenow-fornecedorB

• datadog-ti

• protheus-financeiro

Para entender como configurar Consumers (Chaves de API), confira a documentação.

Cenário de exemplo

Em um cenário hipotético, existe um ERP (SAP) que será consumido por diversos pipelines de diferentes áreas de negócio, mas para fins de controle, não é necessário saber qual área está consumindo os pipelines.

Assim, é possível ter uma única chave de API que identifica que o requisitante daquela API é esse ERP. Dessa forma, o requisitante pode ser identificado como SAP. Porém, nem todos os cenários são tão simples, então é interessante adicionar pelo menos mais um ou dois parâmetros, sendo este o resultado final: sap-rh / sap-ti / sap-finance.

Informações adicionais sobre Consumers (Chaves de API)

• Além de ser a camada mais básica para segurança dos pipelines que serão expostos na internet (é recomendada a utilização junto com JWT), a chave de API é uma maneira eficiente de identificar os consumers do serviço.

• Como existe a possibilidade de uma chave de API ser associada a mais de um pipeline e vice-versa (um pipeline estar a associado a uma ou mais chaves de API), estratégias diferentes podem ser adotadas na hora de definir o padrão de nomenclatura.