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

A definição e estabelecimento de [**Globals**](https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/platform-administration/settings/globals), [**Contas (Accounts)**](https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/platform-administration/settings/accounts), [**Consumers (Chaves de API)**](https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/platform-administration/settings/api-keys-consumers) 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

<figure><img src="https://content.gitbook.com/content/XfrDexGOLMin51pAiWkq/blobs/Fa36SXPBUyEhr2gGQoea/image%20(38).png" alt="" width="563"><figcaption></figcaption></figure>

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](https://docs.digibee.com/documentation/resources/pt-br/best-practices/broken-reference).&#x20;

### Cenário de exemplo

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

* Ambiente de teste:\
  [`https://test.godigibee.io/pipeline/demo/v1/api-extrato-custom-demo`](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)`](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](https://test.godigibee.io) ou[ https://api.godigibee.io](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.&#x20;

* 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.&#x20;

<figure><img src="https://content.gitbook.com/content/XfrDexGOLMin51pAiWkq/blobs/GZf3UspDk4hzpOIDTFbp/image%20(39).png" alt=""><figcaption></figcaption></figure>

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

<figure><img src="https://content.gitbook.com/content/XfrDexGOLMin51pAiWkq/blobs/XVRBIkTWWT9M1p1U7xZy/image%20(40).png" alt="" width="563"><figcaption></figcaption></figure>

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)](https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/platform-administration/settings/accounts).&#x20;

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

<figure><img src="https://content.gitbook.com/content/XfrDexGOLMin51pAiWkq/blobs/WAh9gYvQQeFPcWzGPUdF/image%20(41).png" alt="" width="375"><figcaption></figcaption></figure>

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](https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/platform-administration/settings/api-keys-consumers).&#x20;

### 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.&#x20;

### 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.