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
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-resthost-sap-rfcurl-sap-soapsystemid-sap-rfcurl-servicenow-resthost-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
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:
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-clientidportalabc-rest-clientsecretsqlserver-jdbc-basicsap-rfc-basicsap-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:
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-rhservicenow-fornecedorBdatadog-tiprotheus-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.
Atualizado
