URLs and environments

When your users or customers interact with your API, they will send requests to either a single, central, URL, or 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.

TypeScript

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");

Python

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

class ExcitingSoda:
    def set_base_url(self, url: str) -> None:
        ...

Example:

from excitingsoda import ExcitingSoda

sdk = ExcitingSoda()
sdk.set_base_url("https://eu.exciting.soda")

Java

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

public class ExcitingSoda {
  public void setBaseUrl(String url) {}
}

Example:

import soda.exciting.ExcitingSoda;

ExcitingSoda client = new ExcitingSoda();
client.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:

TypeScript

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);

Python

class Environment(Enum):
    """
    The environments available for this SDK
    """
    DEFAULT = "https://exciting.soda"
    NORTHAMERICA = "https://na.exciting.soda"
    EU = "https://eu.exciting.soda"
    APAC = "https://apac.exciting.soda"

The environment can be set when initializing the SDK:

from .net.environment import Environment

class ExcitingSoda:
    def __init__(self, bearer_token="", environment=Environment.DEFAULT) -> None:
        ...

Example:

from excitingsoda import ExcitingSoda, Environment

sdk = ExcitingSoda(environment=Environment.NORTHAMERICA)

Java

public 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:

public class ExcitingSoda {
  public void setEnvironment(Environment environment) {}
  ...

Example:

import { ExcitingSoda, Environment } from 'excitingsoda';

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

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