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 that you do not know in advance, such as accessing your service on-prem, or via customer specific workspaces.

TypeScript v1

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

TypeScript v2

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

Python v1

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

Python v2

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

Java

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

C#

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

Go

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

PHP

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

When liblab generates your SDK, you can optionally define environments when you know the possible URLs, 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 v1

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

TypeScript v2

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

Python v1

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)

Python v2

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

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

C#

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

Go

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

PHP

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 that points to the default URL described in the default URL section above.