URLs, environments, and server variables

When building APIs, you need to manage URLs to ensure easy access across various environments, customer deployments, and API versions. This documentation page explains how you can configure the default URL used by the generated SDKs to meet different requirements. You can define static environments for different stages or geographic locations, override default URLs for custom deployments, and use server variables to create dynamic, flexible URLs. Each approach allows you to tailor the URL structure to your API's needs, from multi-tenant systems to region-based access or version control.

Default URL

When generating an SDK, liblab uses different sources to determine the default URL for your API. The default URL serves as the primary endpoint that will be used unless overridden by your users. The following list describes how liblab selects the default URL:

Config file (baseURL): The primary source for the default URL is the baseURL defined in your configuration file. If this is set, it becomes the default URL.
OpenAPI Spec (servers section): If no baseURL is specified in the config file, liblab will use the first URL listed in the servers section of your OpenAPI specification.
No URL defined: If your OpenAPI specification does not include a servers section, liblab will raise the following error when generating the SDK:
```
>   Error: OpenAPI "servers" must be present and non-empty array.
```
In this case, the default URL will be set to http://api.example.com, which will fail when you attempt to use the SDK.

Make sure to configure a valid URL to avoid SDK generation errors and ensure proper communication with your API.

Override the default URL

Your SDK users may need to connect to a custom URL when accessing your service via an on-premise server or a customer-specific workspace. They can override the default URL when initializing the SDK to support these cases.

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

The base URL can be set by setting it on the SdkConfig object:

src/http/types.ts
export interface SdkConfig {
  baseUrl: string;
}

This config object can be instantiated directly in the SDK constructor:

src/index.ts
const sdk = new ExcitingSoda({ baseUrl: 'https://eu.exciting.soda' });

You can also set or update the base URL by using the setBaseUrl method:

src/index.ts
export class ExcitingSoda {
  setBaseUrl(baseUrl: string): void {}
  ...
}

Example:

src/index.ts
sdk.setBaseUrl("https://eu.exciting.soda");

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

src/excitingsoda/sdk.py
class ExcitingSoda:
    def set_base_url(self, url: str) -> None:
        ...

Example:

app.py
from excitingsoda import ExcitingSoda

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

You can set the base URL by passing it to the SDK client contrstructor:

src/exciting_soda/sdk.py
class ExcitingSoda:
    def __init__(self, base_url: str = Environment.DEFAULT.value):

Example:

app.py
from exciting_soda import ExcitingSoda

sdk = ExcitingSoda(base_url='https://eu.exciting.soda')

You can also set or update the base URL by using the set_base_url method:

src/exciting_soda/sdk.py
class ExcitingSoda:
    def set_base_url(self, base_url):

Example:

app.py
from exciting_soda import ExcitingSoda

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

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

main/java/soda/exciting/ExcitingSoda.java
public class ExcitingSoda {
  public void setBaseUrl(String url) {}
}

Example:

Main.java
import soda.exciting.ExcitingSoda;

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

The SetBaseUrl method can be used to set the custom URL either from a string or a Uri.

ExcitingSoda/ExcitingSodaClient.cs
public class ExcitingSodaClient
{
    public void SetBaseUrl(string baseUrl)
    {
        SetBaseUrl(new Uri(baseUrl));
    }

    public void SetBaseUrl(Uri uri)
    {
        _httpClient.BaseAddress = uri;
    }
}

Example:

Program.cs
using ExcitingSoda;

var client = new ExcitingSodaClient();
client.SetBaseUrl("https://eu.exciting.soda")

With each SDK, a config struct is created, named according to your SDK:

pkg/excitingsodaconfig/config.go
package excitingsodaconfig

type Config struct {
    BaseUrl *string
}

You can use this when you create your SDK client to set the base URL. For example:

main.go
import (
    "github.com/exciting-soda/exciting-soda-go-sdk/pkg/excitingsoda"
    "github.com/exciting-soda/exciting-soda-go-sdk/pkg/excitingsodaconfig"
)

func main() {
    config := excitingsodaconfig.NewConfig()
    config.SetBaseUrl("https://eu.exciting.soda")
    
    excitingSoda := excitingsoda.NewExcitingSoda(config)
}

The setBaseUrl method can be used to set the custom URL either from a string or a Uri.

src/Client.php
class Client
{
    public function setBaseUrl(string $url)
    {
    }
}

Example:

index.php

$client = new Client();
$client->setBaseUrl('https://eu.exciting.soda');

Environments

Environments allow you to define and switch between predefined URLs based on different stages of development, geographic regions, or testing environments. For example, you can set up testing, staging, and production environments to ensure your users connect to the correct URL for their needs.

If your API is deployed across multiple regions, you can define different environments in your config file. This ensures that your users are automatically directed to the correct environment based on their location or the service they need to access. The following code block presents an example of how environments can be defined in your configuration file:

{
  ...
  "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:

src/http/Environments.ts
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:

src/index.ts
export class ExcitingSoda {
  setEnvironment(environment: Environment): void {}
  ...
}

Example:

src/index.ts
import { ExcitingSoda, Environment } from 'excitingsoda';

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

src/http/environments.ts
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:

src/index.ts
export class ExcitingSoda {
  setEnvironment(environment: Environment): void {}
  ...
}

Example:

src/index.ts
import { ExcitingSoda, Environment } from 'excitingsoda';

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

src/excitingsoda/net/environment.py
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:

src/excitingsoda/sdk.py
from .net.environment import Environment

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

Example:

app.py
from excitingsoda import ExcitingSoda, Environment

sdk = ExcitingSoda(environment=Environment.NORTHAMERICA)

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)

main/java/soda/exciting/Environment.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:

main/java/soda/exciting/ExcitingSoda.java
public class ExcitingSoda {
  public void setEnvironment(Environment environment) {}
  ...
}

Example:

Main.java
import soda.exciting.ExcitingSoda;

public class Main {
  public static void main(String[] args) {
    ExcitingSoda client = new ExcitingSoda();
    client.setEnvironment(Environment.NORTHAMERICA);
  }
}

ExcitingSoda/Http/Environment.cs
public class Environment
{
    public static Environment Default { get; } = new("https://na.exciting.soda/");
    public static Environment NorthAmerica { get; } = new("https://na.exciting.soda/");
    public static Environment Eu { get; } = new("https://eu.exciting.soda/");
    public static Environment Apac { get; } = new("https://apac.exciting.soda/");
}

The environment can be set in 2 ways - being passed to the SDK client constructor, or using the SetEnvironment method:

ExcitingSoda/Config/ExcitingSodaConfig.cs
public record ExcitingSodaConfig(
    /// <value>The environment to use for the SDK.</value>
    Environment? Environment = null
);

ExcitingSoda/ExcitingSodaClient.cs
public class ExcitingSodaClient
{
  public ExcitingSodaClient(ExcitingSodaConfig config) {}
  public void SetEnvironment(Environment environment) {}
  ...
}

To use the constructor, do the following:

Program.cs
using ExcitingSoda;

var config = new ExcitingSodaConfig
{
  Environment = Environment.NorthAmerica
}
;
var client = new ExcitingSodaClient(config);

To use the SetEnvironment method on the client instance, do the following:

Program.cs
using ExcitingSoda;
using ExcitingSoda.Http;

var client = new ExcitingSodaClient();
client.SetEnvironment(Environment.NorthAmerica);

pkg/excitingsodaconfig/config.go
package excitingsodaconfig

const (
    DEFAULT_ENVIRONMENT       = "https://na.exciting.soda"
    NORTH_AMERICA_ENVIRONMENT = "https://na.exciting.soda"
    EU_ENVIRONMENT            = "https://eu.exciting.soda"
    APAC_ENVIRONMENT          = "https://apac.exciting.soda"
)

The environment can be set by updating the base URL in the config object to match the desired environment. This is then used when you create your SDK client.

main.go
import (
    "github.com/exciting-soda/exciting-soda-go-sdk/pkg/excitingsoda"
    "github.com/exciting-soda/exciting-soda-go-sdk/pkg/excitingsodaconfig"
)

func main() {
    config := excitingsodaconfig.NewConfig()
    config.SetBaseUrl(NORTH_AMERICA_ENVIRONMENT)

    excitingSoda := excitingsoda.NewExcitingSoda(config)
}

src/Environment.php
namespace ExcitingSoda;

class Environment
{
    const Default = 'https://na.exciting.soda';
    const NorthAmerica = 'https://na.exciting.soda';
    const Eu = 'https://eu.exciting.soda';
    const Apac = 'https://apac.exciting.soda';
}

The environment can be set when initializing the SDK:

src/Client.php
class Client
{
    public function __construct(string $environment = Environment::Default)
    {
    }
}

Example:

index.php
use ExcitingSoda\Client;
use ExcitingSoda\Environment;

$client = new Client(Environment::NorthAmerica);

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

Server variables

Server variables allow you to configure more flexible URLs by defining placeholders within your server URL. These placeholders are replaced by specific values at runtime. This is particularly useful for multi-tenant systems, API versioning, or if you provide a whitelabel solution.

Environments vs. server variables

Environments are ideal when you have a fixed set of URLs, such as those used for different development stages or geographic locations. For example:

https://api.test.com
https://staging.api.test.com
https://sandbox.api.test.com

In these cases, environments allow you to switch between predefined URLs easily.

Server variables offer more flexibility. They are best used when you need dynamic URLs, such as when each customer has a subdomain such as https://customerName.test.com), where the customerName changes for each user. In addition, server variables are also helpful for maintaining multiple versions of the same API.

You define server variables in your OpenAPI specification within the servers section. These variables allow you to customize aspects such as the subdomain or API version. Use curly braces {} to define variables in the URL template:

"servers": {
  "url": "https://{subdomain}.server.com/{version}",
}

The variables field should be used to declare each server variable, and each must have a default value. In addition, you can define the variable as an enum to restrict its possible values. For additional information about how to use the server variables in your OpenAPI spec, access the OpenAPI documentation.

The following code block presents an example of how to use server variables in your OpenAPI spec:

The following code block shows an example of how to use server variables in an OpenAPI spec for multi-tenant support and API versioning:

"servers": {
  "url": "https://{subdomain}.server.com/{version}",
  "variables": {
    "subdomain": {
      "default": "production",
      "description": "Server used to receive the requests. Use the sandbox while integrating with the system.",
    },
    "version": {
      "default": "v1",
      "description": "API version.",
      "enum": {
        "v1",
        "v2",
        "v3",
      }
    }
  }
}

When you add server variables to your OpenAPI spec, liblab automatically identifies them when generating the SDKs.

note

The server variables feature is available for Python v2. However, liblab is working to expand the supported languages.

The URL configuration will be available when defining the SDK. Your customer can also use setter methods to change the URL dynamically through their code. The following example shows how to initialize the SDK with server variables:

sdk = ExampleSDK(
    subdomain="sandbox", version="v1"
)

The following example shows how to use setter methods to update the URL with the available options:

sdk = ExampleSDK()

sdk.set_subdomain("production")
sdk.set_version(Version.V2)

Default URL​

Override the default URL​

Environments​

Server variables​

Default URL

Override the default URL

Environments

Server variables