api-docs-icon

SDK Customizations

Sideko SDKs can be customized either using a configuration file (sdk-config.yaml), or by implementing extension fields (x-sideko-*) directly into OpenAPI, or a combination of both.

Which Approach is Best for my Team?
  • Teams that choose the config approach: Developer relations, solutions engineering, or sales engineering.
  • Teams that usually choose the x-fields approach: Product engineering and small startup teams

The decision comes down to who owns the OpenAPI specification. The x-fields are easy to add if your team is actively developing the API and it's spec. The config is easy if your team doesn't control the spec, but actively uses it for tooling and documentation.

Quickstart

The configuration file is initialized with all the default values for a given OpenAPI specification using the sideko sdk config init CLI command, see here for more details.

Language Configurations

Language configurations control top-level/global configurations for each SDK language and are currently only available in the configuration file. Some configurations keys are unique for a language and some are common across all languages.

SDK Name

You can customize the package name of the generated SDKs via the sdk_name field in each language.

Example
sdk-config.yaml
languages:
  java:
    sdk_name: deploymentservice
    ...
  python:
    sdk_name: deployment_service
    ...
  typescript:
    sdk_name: "@sideko/deployment-service"
    ...
  ruby:
    sdk_name: deployment_service
    ...
  rust:
    sdk_name: deployment_service
    ...
  go:
    sdk_name: github.com/Sideko-Inc/deployment_service
    ...

Client Name

You can customize class/struct name the generated SDK client name via the class_name field in each language.

Default: Client

Example
sdk-config.yaml
languages:
  java:
    client_name: DeploymentService
    ...
  python:
    ...
  typescript:
    ...
  ruby:
    ...
  rust:
    ...
  go:
    ...

Omitting Operations

If you wish to omit some operations present in your OpenAPI specification from the generated SDK you can do so via the hidden_opertation_id field in each language.

Default: All operations in the OpenAPI specification will be included in the generated SDKs

Example
openapi.yaml
openapi: 3.1.0
...
paths:
  /projects/{id}/deployments:
    get:
      operationId: listDeployments
      ...
    post:
      operationId: createDeployment
      ...
    patch:
      operationId: updateDeployment
      ...

The following language configuration will omit all but the listDeployments method in the generated Typescript SDK.

sdk-config.yaml
languages:
  typescript:
    hidden_operation_ids:
      - createDeployment
      - updateDeployment
    ...
...

Java Configurations

In the java language configuration, the sdk_name documented above will act as your artifactId in your generated SDK's build.gradle. You can also configure the groupId in the build.gradle using the group_id field.

These two fields combined will determine the directory sturcture of your generated Java SDK.

Example
sdk-config.yaml
languages:
  java:
    sdk_name: deploymentservice
    group_id: dev.sideko

This configuration would create the following root directory for the generated Java SDK: src/main/java/dev/sideko/deploymentservice

Rust Configurations

In the rust language configuration, the cli field can be used to include a fully functional CLI in the generated SDK alongside the usual generated client, method, types, and tests.

Example
sdk-config.yaml
languages:
  rust:
    sdk_name: deployment_service
    cli: true

This configuration means the rust SDK will have a CLI capability behind a feature cli. To run this CLI locally before building run in the root of the generated rust SDK: cargo run --features=cli -- --help

You can read more about CLI generation here.

Server Customizations

In OpenAPI you can define many base URLs for your API using the servers root key. Sideko will generate constants for each of these base URLs to allowing SDK users to easily specify which environment they are interacting with on client initialization.

Configuration Props
name
stringdefault: environment_{n}

This name will be converted into the relevant case in the target generation language.

OpenAPI extension key: x-sideko-name

default
booleandefault: false

The default server which the SDK should interact with. This name will be converted into the relevant case in the target generation language.

OpenAPI extension key: x-sideko-default

Example

Given an OpenAPI:

openapi.yaml
openapi: 3.1.0
...
servers:
  - url: https://api.example.com/v1
    description: Production server (uses live data)
  - url: https://sandbox-api.example.com:8443/v1
    description: Sandbox server (uses test data)

Configured with:

sdk-config.yaml
servers:
  - url: https://api.example.com/v1
    name: production
    default: true
  - url: https://sandbox-api.example.com:8443/v1
    name: staging
...
openapi.yaml (with extensions)
openapi: 3.1.0
...
servers:
  - url: https://api.example.com/v1
    description: Production server (uses live data)
    x-sideko-name: production
    x-sideko-default: true
  - url: https://sandbox-api.example.com:8443/v1
    description: Sandbox server (uses test data)
    x-sideko-name: staging

Authentication Customizations

OpenAPI allows for a many API authentication methods to be defined for a single API. Depending on the language, these authentication methods will turn into params for client initialization (e.g. Python, Typescript) or client builder methods (e.g. Go, Rust, and Java).

Basic Auth Configuration Props
username-param
stringdefault: username

The param name will be converted to the relevant case for the target language.

OpenAPI extension key: x-sideko-username-param

password-param
stringdefault: password

The param name will be converted to the relevant case for the target language.

OpenAPI extension key: x-sideko-password-param

Bearer, API Key, OAuth2 Configuration Props
param
stringdefault: token or api_key or oauth_token (according to auth type)

The param name will be converted to the relevant case for the target language.

OpenAPI extension key: x-sideko-param

Example

Given an OpenAPI:

openapi.yaml
openapi: 3.1.0
...
components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    BearerAuth:
      type: http
      scheme: bearer
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

Configured with:

sdk-config.yaml
auths:
  - id: BasicAuth
    username_param: user
    password_param: pw
  - id: BearerAuth
    param: api_token
  - id: ApiKeyAuth
    param: api_secret
...
openapi.yaml (with extensions)
openapi: 3.1.0
...
components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      x-sideko-username: user
      x-sideko-password: pw
    BearerAuth:
      type: http
      scheme: bearer
      x-sideko-param: api_token
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      x-sideko-param: api_secret

Module & Function Customizations

Sideko will automatically create module paths and function names based on the paths and methods listed in the OpenAPI specification. These can be customized using the modules (array[ModuleConfig]) field in the configuration file or with the following extensions in OpenAPI:

Configuration Props
Extension KeyTypeExampleNotes
x-sideko-modulestringprojects.deploymentsEach dot-delimited value in the list will be converted into the relevant case in the target generation language.
x-sideko-function-namestringtriggerThe function name will be converted into the relevant case in the target generation language.

Example

Given an OpenAPI:

openapi.yaml
openapi: 3.1.0
...
paths:
  /projects:
    post:
      operationId: createProject
      ...
  /projects/{id}/deployments:
    get:
      operationId: listDeployments
      ...
    post:
      operationId: createDeployment
      ...

Configured with:

sdk-config.yaml
modules:
  - path: proj
    operations:
      - id: createProject
        function_name: create
  - path: proj.deploy
    operations:
      - id: listDeployments
        function_name: list
      - id: createDeployment
        function_name: trigger
openapi.yaml (with extensions)
...
openapi: 3.1.0
...
paths:
  /projects:
    post:
      operationId: createProject
      x-sideko-module: proj
      x-sideko-function-name: create
      ...
  /projects/{id}/deployments:
    get:
      operationId: listDeployments
      x-sideko-module: proj.deploy
      x-sideko-function-name: list
      ...
    post:
      operationId: createDeployment
      x-sideko-module: proj.deploy
      x-sideko-function-name: trigger
      ...

With this configuration you can expect the following methods to be generated:

# Python SDK
client.proj.create()
client.proj.deploy.list()
client.proj.deploy.trigger()
// Go SDK
client.Proj.Create()
client.Proj.Deploy.List()
client.Proj.Deploy.Trigger()
// Java SDK
client.proj().create();
client.proj().deploy().list();
client.proj().deploy().trigger();
// Rust SDK
client.proj().create();
client.proj().deploy().list();
client.proj().deploy().trigger();
// Typescript SDK
client.proj.create()
client.proj.deploy.list()
client.proj.deploy.trigger()

Is there a configuration you wish we supported? Contact us or open an issue on Github to submit a request