Naming: Global, Accounts and API Keys
The definition and establishment of Globals, Accounts and Consumers (API Keys) are part of the Digibee Integration Platform setup and practically all flows will use one or more of these configurations during their execution.
Best naming practices
Combine clear prefixes to identify the purpose and context of each element.
Use lowercase letters.
Separate words using a hyphen (-).
It is extremely important that definitions are well classified and named to avoid duplication, overlap and even misuse within the flows.
Globals
When naming Globals, it is recommended to use three parameters to compose the name:
Category
URL
host
systemid
System
SAP
VTEX
ServiceNow
Oracle
Protheus
Technology
REST
SOAP
JDBC
RFX
Once all the integration parameters have been identified, we can compose the name of the Global, as in the examples below:
url-vtex-resthost-sap-rfcurl-sap-soapsystemid-sap-rfcurl-servicenow-resthost-oracle-jdbc
Read the documentation to learn the step-by-step process for creating a Global.
Example scenario
In this scenario, it is necessary to perform an integration with a REST endpoint with the following URLs:
Test environment:
https://test.godigibee.io/pipeline/demo/v1/api-extrato-custom-demo
Production environment:
The service host is located in the following section: https://test.godigibee.io or https://api.godigibee.io.
The rest https://test.godigibee.io/pipeline/demo/v1/api-extrato-custom-demo is the path referring only to the service that will be used in this integration.
Only the first section must be registered in Global.
The rest must be used directly in the pipeline. In other words, another global must be created to store the path, especially in cases where the path changes according to the environment in which it will be executed.
Accounts
Just like in the Globals registry, the same reasoning is used to catalog and standardize the nomenclature of Accounts, with the same approach to defining prefixes. The recommendation is to organize Accounts based on three parameters:
Below are some of the most common use cases in integrations:
System
SQLServer
portalabc
SAP
Technology
REST
JDBC
RFC
Type
clientdid
clientsecret
basic
Once all the integration parameters have been identified, it is possible to compose the Account name, as in the examples below:
portalabc-rest-clientidportalabc-rest-clientsecretsqlserver-jdbc-basicsap-rfc-basicsap-jdbc-clientid
To understand how to configure each type of account, access the Accounts documentation.
Consumers (API Keys)
In the previous records, the same reasoning was adopted to catalog and standardize the nomenclature of Consumers (API Keys), with the same approach for defining prefixes. The recommendation is to organize the nomenclature based on two parameters:
Below are some of the most common use cases in integrations:
System
SAP
Protheus
Servicenow
Datadog
Business unit / Supplier
HR
IT
Supplier A
Supplier B
Once all the integration parameters have been identified, it is possible to compose the name of the Consumers (API Keys), as in the examples below:
sap-rh
servicenow-supplierB
datadog-ti
protheus-financial
Example scenario
In a hypothetical scenario, there is an ERP (SAP) that will be consumed by several pipelines from different business areas, but for control purposes, it is not necessary to know which area is consuming the pipelines.
Therefore, it is possible to have a single API key that identifies that the requester of that API is this ERP. In this way, the requester can be identified as SAP. However, not all scenarios are so simple, so it is interesting to add at least one or two more parameters, with this being the final result: sap-rh / sap-ti / sap-finance.
Additional information about Consumers (API Keys)
In addition to being the most basic layer for security of pipelines that will be exposed on the internet (usage together with JWT is recommended), the API key is an efficient way to identify consumers of the service.
Since it is possible for an API key to be associated with more than one pipeline and vice versa (a pipeline being associated with one or more API keys), different strategies can be adopted when defining the naming standard.
Last updated
