Tags:
Categories:

Create/update an API client

Guidelines for the generation or the update of an API client in Aura

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:

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.
Last modified May 18, 2026: Remove KGB (52b04d91)