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]-[system]-[technology]

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-rest

• host-sap-rfc

• url-sap-soap

• systemid-sap-rfc

• url-servicenow-rest

• host-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:

https://api.godigibee.io/pipeline/demo[/v1/api-extrato-custom-demo](https://test.godigibee.io/pipeline/demo/v1/api-extrato-custom-demo)

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:

[system]-[technology]-[type]

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-clientid

• portalabc-rest-clientsecret

• sqlserver-jdbc-basic

• sap-rfc-basic

• sap-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:

[ConsumerSystem]-[BusinessUnit/Supplier]

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.