Skip to main content

URLs and environments

When your users or customers interact with your API, they might send requests to either a single, central, URL, or they might need to use different URLs depending on the customer, location, or environments.

For example, if you have a single URL that all customers use, then they might access:

https://exciting.soda

You may have different environments, such as a private preview environment, or different deployment locations:

https://preview.exciting.soda
https://eu.exciting.soda
https://apac.exciting.soda

If you manage different deployments for different customers, or customized workspaces, then they might access:

https://my-customer-name.exciting.soda

You might also have on-prem deployments, so your customers might access internal URLs:

https://exciting.soda.my-customer-name.com/

This guide will walk you through how liblab determines the default URL for your API, and how you can customize it, including allowing your users to specify their own URLs, or configure different URLs for different environments.

Default URL

When you generate an SDK, liblab will use a number of different sources to determine the default URL for your API.

  1. If you have specified a baseURL in your config file, then this will be the default URL

  2. If you have not specified a baseURL in your config file, the URL will be picked up from the servers section of your API spec. If you have multiple servers, the first one is chosen.

  3. If you do not have a servers section in your API spec, then you will get an error when you try to generate your SDK:

    >   Error: OpenAPI "servers" must be present and non-empty array.

    In this case, the default URL will be http://api.example.com. This will fail when you try to use the SDK.

Override the default URL

Your SDK users can directly set the base URL to use when initializing the SDK. This allows for custom URLs, such as accessing your service on-prem, or via customer specific workspaces.

The setBaseUrl method can be used to set the custom URL.

export class ExcitingSoda {
setBaseUrl(url: string): void { }
...

Example:

import { ExcitingSoda } from 'excitingsoda';

const sdk = new ExcitingSoda();
sdk.setBaseUrl("https://eu.exciting.soda");

Environments

When liblab generates your SDK, you can optionally define environments, for example for preview versions or different locales. These are defined in the config file.

For example, if you have the following environments defined:

{
...
"customizations": {
"environments": [
{
"name": "NorthAmerica",
"url": "https://na.exciting.soda"
},
{
"name": "EU",
"url": "https://eu.exciting.soda"
},
{
"name": "APAC",
"url": "https://apac.exciting.soda"
}
]
}
}

Then in the SDK code, these environments will be defined, and they can be set when initializing the SDK:

export enum Environment {
DEFAULT = 'https://exciting.soda',
NORTHAMERICA = 'https://na.exciting.soda',
EU = 'https://eu.exciting.soda',
APAC = 'https://apac.exciting.soda',
}

The environment can be set using the setEnvironment method:

export class ExcitingSoda {
setEnvironment(environment: Environment): void {}
...
}

Example:

import { ExcitingSoda, Environment } from 'excitingsoda';

const sdk = new ExcitingSoda();
sdk.setEnvironment(Environment.NORTHAMERICA);

In addition to the environments defined in the config file, there will always be a DEFAULT environment that points to the default URL described in the default URL section above.