Configure Multiple Server URLs

Base Server Configuration

By default, the OpenAPI spec allows you define an array of servers that can be used to make requests to the API. These servers are generally used to define different environments available for the API, but the OpenAPI spec while allowing you to add a description doesn't provide a strongly typed way to define which server to use by default (normally the production environment). The Speakeasy SDK Generator will by default use the first url in the array, meaning that someone using the SDK will be hitting that first defined server.

openapi: 3.0.3
info:
  title: Example
  version: 0.0.1
servers:
  - url: https://prod.example.com # Used as the default URL by the SDK
    description: Our production environment
  - url: https://sandbox.example.com
    description: Our sandbox environment

If you your OpenAPI document doesn't define any servers (either globally or per operation) then you will need to define the base server URL in the SDK Generator configuration. This is done by adding a baseserverurl property to the gen.yaml file.

# ...
baseserverurl: "https://prod.example.com"

While the SDK generator will use the first server in the array (or the configured baseserverurl in the gen.yaml file) as the base URL for all requests, you can configure the SDK at runtime to use a different server like below:

Go

// With a custom address
opts := []sdk.SDKOption{
    sdk.WithServerURL("https://example.com"),
}
// or with one of the servers in the generated servers array
opts := []sdk.SDKOption{
    sdk.WithServerURL(sdk.Servers[0]),
}

s := sdk.New(opts)

Python

s = sdk.SDK()

# With a custom address
s.config_server_url("https://example.com")
# or with one of the servers in the generated servers array
s.config_server_url(sdk.SERVERS[0])

Typescript

// With a custom address
const opts = [WithServerURL("https://example.com")];
// or with one of the servers in the generated servers array
const opts = [WithServerURL(Servers[0])];

const s = new SDK(opts);

Java

SDK.Builder builder = SDK.builder();

// With a custom address
builder.setServerURL("https://example.com");
// or with one of the servers in the generated servers array
builder.setServerURL(SDK.SERVERS[0]);

SDK sdk = builder.build();

Server URLs also support templating to allow you to define variables in the URL that can be replaced at runtime. For example, if you have a server URL like https://{variable}.example.com you can replace the {variable} variable with a value like below:

Go

// Pass a map of variables to replace those matching the server URL
opts := []sdk.SDKOption{
    sdk.WithServerURL("https://{variable}.example.com", map[string]string{
        "variable": "value",
    }),
}

Python

# Pass a dict of variables to replace those matching the server URL
s.config_server_url("https://{variable}.example.com", {"variable": "value"})

Typescript

// With an object of variables to replace those matching the server URL
const opts = [
  WithServerURL("https://{variable}.example.com", {
    variable: "value",
  }),
];

Java

SDK.Builder builder = SDK.builder();

// With an object of variables to replace those matching the server URL
builder.setServerURL("https://{variable}.example.com", new HashMap<String, String>() {{
    put("variable", "value");
}});

Speakeasy Server Extensions

Passing URLs or index numbers to a URL in the servers array can be cumbersome and doesn't provide a great developer experience. To make this easier, Speakeasy provides an extension to the OpenAPI spec that allows you to define an ID for each server in the Servers array. This can be done using the x-speakeasy-server-id property on the server object.

openapi: 3.0.3
info:
  title: Example
  version: 0.0.1
servers:
  - url: https://prod.example.com # Used as the default URL by the SDK
    description: Our production environment
    x-speakeasy-server-id: prod
  - url: https://sandbox.example.com
    description: Our sandbox environment
    x-speakeasy-server-id: sandbox

This extension then enables the below configuration of the SDK at runtime:

Go

// With a constant containing the server ID
opts := []sdk.SDKOption{
    sdk.WithServer(sdk.ServerProd),
}

s := sdk.New(opts)

Python

s = sdk.SDK()

# With a constant containing the server ID
s.config_server(sdk.SERVER_PROD)

Typescript

// With a constant containing the server ID
const opts = [WithServer(ServerProd)];

Java

SDK.Builder builder = SDK.builder();

// With an enum containing the server ID
builder.setServer(SDK.Servers.PROD);

A map/dict can still be passed as an optional second argument if the server URLs are templated and the methods to define a specific server URL are also still available.