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 thebaseURL
defined in your configuration file. If this is set, it becomes the default URL. - OpenAPI Spec (
servers
section): If nobaseURL
is specified in the config file, liblab will use the first URL listed in theservers
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:In this case, the default URL will be set to> Error: OpenAPI "servers" must be present and non-empty array.
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.
- TypeScript v1
- TypeScript v2
- Python v1
- Python v2
- Java
- C#
- Go
- PHP
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:
export interface SdkConfig {
baseUrl: string;
}
This config object can be instantiated directly in the SDK constructor:
const sdk = new ExcitingSoda({ baseUrl: 'https://eu.exciting.soda' });
You can also set or update the base URL by using the setBaseUrl
method:
export class ExcitingSoda {
setBaseUrl(baseUrl: string): void {}
...
}
Example:
sdk.setBaseUrl("https://eu.exciting.soda");
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")
You can set the base URL by passing it to the SDK client contrstructor:
class ExcitingSoda:
def __init__(self, base_url: str = Environment.DEFAULT.value):
Example:
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:
class ExcitingSoda:
def set_base_url(self, base_url):
Example:
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.
public class ExcitingSoda {
public void setBaseUrl(String url) {}
}
Example:
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
.
public class ExcitingSodaClient
{
public void SetBaseUrl(string baseUrl)
{
SetBaseUrl(new Uri(baseUrl));
}
public void SetBaseUrl(Uri uri)
{
_httpClient.BaseAddress = uri;
}
}
Example:
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:
package excitingsodaconfig
type Config struct {
BaseUrl *string
}
You can use this when you create your SDK client to set the base URL. For example:
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
.
class Client
{
public function setBaseUrl(string $url)
{
}
}
Example:
$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:
- TypeScript v1
- TypeScript v2
- Python v1
- Python v2
- Java
- C#
- Go
- PHP
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);
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);
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, environment=Environment.DEFAULT) -> None:
...
Example:
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)
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 soda.exciting.ExcitingSoda;
public class Main {
public static void main(String[] args) {
ExcitingSoda client = new ExcitingSoda();
client.setEnvironment(Environment.NORTHAMERICA);
}
}
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:
public record ExcitingSodaConfig(
/// <value>The environment to use for the SDK.</value>
Environment? Environment = null
);
public class ExcitingSodaClient
{
public ExcitingSodaClient(ExcitingSodaConfig config) {}
public void SetEnvironment(Environment environment) {}
...
}
To use the constructor, do the following:
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:
using ExcitingSoda;
using ExcitingSoda.Http;
var client = new ExcitingSodaClient();
client.SetEnvironment(Environment.NorthAmerica);
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.
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)
}
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:
class Client
{
public function __construct(string $environment = Environment::Default)
{
}
}
Example:
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 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.
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)