Aura API clients

• 1: Internal API clients
• 2: External API clients
• 3: Create/update an API client

1 - Internal API clients

Internal API clients

Introduction

Internal API clients in Aura are associated with Aura servers. They are automatically generated and published with changes in the API definition of its server during the CI execution, the developer does nothing to update it.

The self-generated clients are clients automatically generated and published with changes in the API definition of its server during the CI execution, the developer does nothing to update it.

Almost all servers developed by the aura-bot team belong to this set, but not all. For instance, aura-bridge client, as its complete swagger is built out of the different partial swaggers of aura-bridge core and all its plugins, is generated and stored in aura-clients repository instead of in aura-bridge repository, as would happen with the self-generated clients.

Aura cognitive client

This client provides a set of classes to interact with the Telefónica Cognitive Service. It implements version 3.4.0.

These classes are:

• DomainClassifierApi: interaction with Telefónica’s Domain Classifier Cognitive Service. This service is no longer used by aura-bot, because the updated version is the one available in aura-nlp-client.
• InsightsResolutionApi: interaction with Telefónica’s Insights Resolution Classifier Cognitive Service passing the base path where the service is hosted and the user OAuth access token to use when interacting with the remote service.
• SuggestionsApi: interaction with Telefónica’s Suggestions Cognitive Service passing the base path where the service is hosted and the user OAuth access token to use when interacting with the remote service.
• NotificationsFilterApi: interaction with the Telefónica’s NotificationFilter Cognitive Service.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/aura-cognitive-client/

📄 Access this API client in the Github repository: aura-cognitive-client

Movistar+ cognitive client

This client provides a set of classes to interact with the Movistar+ cognitive Service.

These classes are:

• MovistarPlusCognitiveClient: Interaction with Movistar+ Resolution Cognitive Service passing the base path where the service is hosted and the user OAuth access token to use when interacting with the remote service.
• MovistarPlusCognitiveStatusClient: Interaction with Movistar+ Resolution Status Cognitive Service passing the base path where the service is hosted and the user OAuth access token to use when interacting with the remote service.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/movistar-plus-cognitive-client/

Aura NLP client

This client implements the internal NLP API that provides access to the aura-bot nlp-recognizer-middleware. It implements the client for the 3.0.0. version of the API.

It provides access to DomainClassifierApi: interaction with Telefónica’s Domain Classifier Cognitive Service.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/aura-nlp-client/

📄 Access the aura-nlp API definition

Aura authentication client (autogenerated)

This client implements the internal authentication API that provides access to the Aura user’s service. It implements the client for the 2.2.0. version of the API and provides access to UsersApi.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/authentication-api-client/

📄 Access the aura-authentication-api API definition

Find more information in the Github repository:

Aura File Manager client

This client implements the internal API that provides access to the aura-file-manager component. It implements the client for the 2.2.0. version of the API and provides access to the File Manager API, microservice responsible of handling attached files storage and validations at channel level.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/aura-file-manager-client/

📄 Access the aura-file-manager API definition

Aura Configuration Client

This client implements the API that provides access to the aura-configuration-api component. It implements the client for the 2.3.0. version of the API.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/aura-configuration-api-client/

📄 Access the aura-configuration-api API definition

Aura Bridge client

The aura-bridge client contains a set of endpoints that support aura-bridge, that is, Aura component in charge of adapting the communication protocol between aura-groot and certain external channels, such as Whatsapp, that cannot implement the Direct Line protocol.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/aura-bridge-client/

📄 Access the aura-bridge API definition

Aura Complex Logic client

This client implements the API that provides access to the aura-complex-logic component in Aura.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/complex-logic-client/

📄 Access the aura-complex-logic API definition

Aura Gateway API client

This client implements the API that provides access to the aura-gateway-api service in Aura.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/aura-gateway-api-client/

📄 Access the aura-gateway-api API definition

Agents Manager API client

This client implements the API that provides access to the agents-manager service in Aura.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/aura-agents-manager-client/

2 - External API clients

External API clients

Introduction

External API clients are associated with services external to Aura.

They are located inside the Github repository @telefonica/aura-clients, which is a Github private repository shared with Telefonica’s LCDO.

Kernel API clients

Aura contains different Kernel API clients for interacting with Telefónica Kernel products, which are described in the following sections.

You can access to the corresponding swaggers, per environment and country, here.

Find more information in the Github repository for the kernel-directsql-api-client: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/kernel-directsql-api-client/

Access Sessions client

Implementation of the Kernel Access Sessions API.

It provides a SingleAccessSessionApi class with all the models and methods implemented to handle Access Sessions API.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/aura-bot-access-sessions-client/

Aura Bot Events client

Implementation of the Kernel Aura Bot Events API.

It provides an API class to handle AuraBotEvent, with all the models and methods implemented to be able to handle this API.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/aura-bot-events-client/

Invoicing client

Implementation of the Kernel Invoicing API v2.

It provides a central class called InvoicingClient that makes it the very simple to interact with Telefónica Kernel Invoicing Service, passing the base path where the service is hosted and the user OAuth access token to use when interacting with the remote service.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/invoicing-client/

Mobile Balance client

Implementation of Kernel Mobile Balance API

It provides a couple of classes called BalanceClient and TopUpClient that makes it very simple to interact with Telefónica Kernel Mobile Balance Service, passing the base path where the service is hosted and the user OAuth access token to use when interacting with the remote service.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/mobile-balance-client

Mobile Quota client

Implementation of Kernel Mobile Quota API

It provides a central class called MobileQuotaClient that makes it the very simple to interact with Telefónica Kernel Mobile Quota Service, passing the base path where the service is hosted and the user OAuth access token to use when interacting with the remote service.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/mobile-quota-client

Smart Wifi client

Implementation of Kernel Smart Wifi API

It provides a central class called SmartWifiClient which makes it very simple to interact with Telefónica Kernel Smart Wifi Service passing the base path where the service is hosted and the user OAuth access token to use when interacting with the remote service.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/smart-wifi-client/

Subscribed Products client

Implementation of Kernel Subscribed Products API

It provides a central class called SubscribedProductsClient which makes it very simple to interact with Telefónica Kernel Subscribed Products Service passing the base path where the service is hosted and the user OAuth access token to use when interacting with the remote service.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/subscribed-products-client/

User Profile client

Implementation of the Kernel User Profile API

It provides a UserApi class with all models and methods needed to handle user profile requests.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/user-profile-client/

WhatsApp API client

Implementation of the Kernel WhatsApp API

It provides a WhatsApp API class with all models and methods needed to handle WhatsApp requests.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/whatsapp-api-client/

Genesys API client

The common call center solution in Telefonica OBs is a platform called Genesys.

The current client is an implementation of the Genesys API version 8.5.2, that is compatible with the call center platform of all the OBs. It is required in order to provide the internal handover to agent solution in Aura.

As Genesys API is not defined with OpenAPI, we have gathered all the methods and objects needed to handle Genesys requests and provide the API definition by our own.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/genesys-api-client/

Aura AI Service API client

Implementation of the aura-ai-services

It provides FeedbackApi, GenerativeApi, NlpaasApi classes with all the models and methods implemented to handle requests to aura-ai-services.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/aura-aiservices/

Agents API client

Implementation of the agents-api

It provides DefaultApi class with all the models and methods implemented to handle requests to agents-api.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/aura-aiservices/

3 - Create/update an API client

Create/update an API client

Introduction

There are two main ways to create or update a new API client, both based on a swagger OpenAPI schema:

• Create a new client based on a swagger
• Update an already available client by re-creating it based on the next version of the published swagger

API clients are generated automatically from the swagger file delivered by the API constructor, usually Telefónica Kernel. Aura uses a custom code generator based on the OpenAPI initiative in order to generate TypeScript clients, which is compatible with JavaScript. Two different types of clients live together in the current Aura release:

• Clients generated directly from the swagger with the original code generator described on the swagger documentation.
• Clients generated directly from the swagger based on the custom code generator. ℹ️ Recommended way.

A copy of the swagger generator tools is available in the repository in the folder called tools, to be used directly from the scripts of the client. In the current version, we are using aura-code-generator/packages/aura-client-generator/tools/openapi/openapi-generator-cli-6.2.1.jar as the custom code generator.

Procedures for generating or updating clients

There are three different processes, depending on the type of client and purpose:

• Create a new external client for a brand-new API
• Create a new internal client for a brand-new API
• Update a client to a breaking change version

Moreover, if implementing a minor change version, check how the original client was created and follow the same procedure. Otherwise, there can be uncontrolled breaking changes.

Previous to the creation of a client, it is required to install the library: @telefonica/aura-develop-utilities

Create a new external client

We have integrated Hygen as a way to boost the process of creating new API clients.

To create a new API client template, please follow the next steps:

1. In your project install the client generator: $ @telefonica/aura-client-generator
2. Create a new branch with a descriptive name: $ git branch -b feat/new-api-client
3. Execute the following commands to create or update API:
   • $ aura-client-generator, $ aucg or $ aura-cg: Generate new API with base files, model files and API files.
   • $ aucg-update: Generate only API files.
   • $ aucg-model: Generate only model files.
4. Send answers for aucg.
   • Hygen: Answer the questions requested by the Hygen for the generation of the new client. Hygen will ask you for the name of the new API, the location of the swagger, the location where you want to generate the client (by default, it is generated in the root directory with the name of client), the version, the enumeration, the projectType and the tag to be set.
   • Flags options: Add flags options with the answers.
     • $ -V, --version: output the version number
     • $ --clientName: Which is the name of the new API (ex.: Admin, User Authentication, etc.)?
     • $ --swaggerFile: Path of the swagger
     • $ --clientDirectory: In which directory do you want to generate the client (default: “client”)
     • $ --versionNumber: Client version
     • $ --tagName: Tag used in the publishConfig configuration (default: “”)
     • $ --enumeration: Enumeration format (choices: “Unchange”, “Unify”, “Particularize”, default: “Unchange”)
     • $ --projectType: Destination project type (choices: “client”, “server”, default: “client”)
     • $ -h, --help: display help for command

Enumeration question

It is a list of options from which you can choose the specific way the models are generated.

• Unchange: No modification is applied to names, enums or interfaces themselves. (If the swagger has several schemas with the same name, they will step on each other).
• Unify: This option unifies in a single enum or interface the schemas that may have the same name. (Recommended option).
• Particularize: This option separates all enums that have the same name by assigning the name of the enum + the name of the schema it belongs to.

projectType question

It is a list from which you can choose the type of client: external client (client) or internal client (server). This question is asked since the aura-code-generator is used to generate these two types of clients and certain elements change in the generation of each type.

• client: make reference to the external client.
• server: make reference to the internal client.

Note that when Hygen asks for the location for the new client, the format of this folder name must be a dash-separated name similar to name-of-your-api or ./package/name-of-your-api only in external clients.

In the background, the aura-client-generator command carries out the following steps:

1. Create a new package for the new API client at the indicated address directory.
2. Create the .gitignore, .npmignore, .npmrc, package.json, README.md and tsconfig.json files in the new API client package directory.
3. Create a new src/ folder in the new API client package directory.
4. Create the index.ts, models.ts files and a folder called api inside this API folder.
5. The provided Swagger API specification file is copied to the swagger directory of the new API client package directory.

At this stage, developers are ready to start working on the new API client from the newly created API client template:

1. Write a description of the new client and a minimal usage example in the README file.
2. Commit your changes and push them to Github.
3. Make a Pull Request to merge your changes in master/main branch.
4. After approved, merge the PR into master/main branch.
5. Then, the new version of the client is published in the private npm registry and available to be used.

Once the creation of the new client is finished, follow the guidelines to contribute your changes according to Contributing code to the repository section.

Create a new internal client

In order to create an internal client, execute the following command:
$ npm run create-client

This will execute the process that will generate a new client, internal clients do not execute hygen as in external clients since all the information they need is passed to them through the flags that are explained below.

The complete command executed is the following:
$ npx aucg --clientName \"server name\" --swaggerFile \"swagger path\" --projectType \"server\"

Where:

• npx aucg: command that executes the aucg
• --swaggerFile: Location of the server swagger.
• --projectType: Type of project, among the ones defined in enumeration projectType. In this case, it is server because it is an internal client. (Remember that this same generator is also used for external clients selecting the projectType client).

Steps to upload changes:

1. Write a description of the new client and a minimal usage example in the README file.
2. Commit your changes and push them to Github.
3. Make a Pull Request to merge your changes in master/main branch.
4. After approved, merge the PR into master/main branch.
5. Then, the new version of the client is published in the private npm registry and available to be used.

Once the creation of the new client is finished, follow the guidelines to contribute your changes according to Contributing code to the repository section.

Update a client

ℹ️ This procedure is valid both for external and internal clients

Due to the superagent HTTP library migration of all clients, a new procedure to update those clients has been implemented.

In addition, this new implementation depends on templates, which can be found here. If there are changes in the template that need to be reflected in a client, before continuing with this procedure, you should create a PR with those changes in templates and merge them into master/main branch.

The procedure to update a client with an updated template is as follows:

1. Create a new branch for the new code:
   git checkout -b feat-or-fix-or-chore-depending-on-the-update/the-name-of-your-branch
2. If needed, add a tag or, if it has already been added, increase the numeric version in the package.json version:
   "version": "2.1.0-superagent.x",
3. Execute the following command to update the client APIs:
   npm run swagger-generate-client
4. Execute the following command to update the client models:
   npm run swagger-generate-model
5. Commit your changes and push them to Github.
6. Make a Pull Request to merge your changes in master.
7. After approved, merge the PR into master.
8. Then, the new version of the client is published in the private npm registry and available to be used.

Authentication methods

All clients are generated using a common template for OpenAPI generator, so they have similar structure: all of them have a generic constructor to set a basePath endpoint: constructor(basePath?: string);

If no basePath is defined, which is not recommended, the default basePath defined on swagger file is used.

The current client generator supports several authentication methods based on swagger security definitions. The available authentication methods are described in the following sections.

Basic authentication

This authentication method is based on user and password.

Credentials can be set by different forms:

• Using constructor. Credentials can be set on constructor using this method:

  constructor(basePathOrUsername: string, password?: string, basePath?: string)
  

• Using setters. Credentials can be set using username and password setters:

  clientInstance.username = 'myuser'; clientInstance.password = 'mypassword';
  

Bearer authentication

This authentication method is based on a bearer token standard. It injects an Authorization header on HTTP request.

It can be set using the setter:
accessToken: clientInstance.accessToken = 'token'

The token can contain a bearer prefix or not. If no bearer prefix is included, the setter method adds it automatically.

Oauth authentication

This authentication method is based on oauth authentication standard. It is similar to bearer authentication method, so an authorization header is injected on HTTP request.

It can be set using the setter:
accessToken: clientInstance.accessToken = 'token'

The token can contain a Bearer prefix or not. If no Bearer prefix is included, the setter method adds it automatically.

Apikey authentication

This authentication method is based on APIKey authentication standard. It injects a generic header with key and value.

It can be set by using setApiKey method with the key and value parameters:
clientInstance.setApiKey(key: string, value:string);

None

If no security schema is defined in the API definition file or the security methods do not follow any OpenAPI standards, a generic accessToken setter is provided. This setter works as bearer and it injects an authorization header on HTTP request.

It can be set using the setter:
accessToken: clientInstance.accessToken = 'token'

The token can contain a bearer prefix or not. If no bearer prefix is included, the setter method adds it automatically.

Contributing code to the repository

To contribute your code to the repository, follow the next steps:

1. Once the code is satisfactory, stash changes into your branch.
2. Push your branch to the remote repository (this step runs the unit tests of all the packages and does not let the process continue until of all them have passed):

   git push origin feat-or-fix-or-chore-depending-on-the-update/name-of-your-branch
   

3. From Github, send a new Pull Request from the branch with your code to master.
4. Ask for revision from any of the main contributors of the project.
5. Once the code has been reviewed and accepted, merge your code into master.