SDK language options
The language options are used to customize the SDK generation on a per-SDK language basis.
- Generic language options
- C# specific options
- Go specific options
- Java specific options
- PHP specific options
- Python specific options
- Terraform specific options
- TypeScript specific options
Generic language options
These options are applicable to all SDK languages, and are set on a per-language basis in the specific SDK language section. For example, the sdkVersion
can be set to different values for each language SDK:
{
...
"languageOptions": {
"typescript": {
"sdkVersion": "1.0.0-alpha"
},
"python": {
"sdkVersion": "1.0.0-beta"
},
"java": {
"sdkVersion": "1.0.0-beta-2"
}
}
...
}
Option | Type | Required | Default | Description |
---|---|---|---|---|
liblabVersion | string | ❌ | language dependant | The version of liblab SDK generation to use |
githubRepoName | string | ❌ | N/A | The name of the GitHub repository for the SDK |
targetBranch | string | ❌ | main | The branch to create the pull request against |
ignoreFiles | array | ❌ | N/A | A list of files to ignore when generating the SDK |
sdkVersion | string | ❌ | N/A | The version of the SDK |
hookDependencies | array | ❌ | N/A | Additional dependencies for hooks |
authors | array | ❌ | N/A | The authors of the SDK. These values are added to the relevant package manifest. This is not supported for Java SDKs |
homepage | string | ❌ | N/A | The URL for the homepage for this SDK. This is added to the relevant package manifest |
additionalConstructorParameters | array | ❌ | [] | Additional parameters to add to the SDK client constructor. These parameters can then be accessed in hooks. |
liblabVersion
Supported SDK languages and versions:
TypeScript v1 TypeScript v2 Java v1 Java v2 Python v1 Python v2 C# Go PHP ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
The liblabVersion
setting sets the version of the liblab SDK generation to use.
For example, to use v2 of liblab to generate a Python SDK, use the following:
{
"languages": [
"python"
],
"languageOptions": {
"python": {
"liblabVersion": "2"
}
}
}
The default value of this option depends on the SDK language. These default versions, along with the available versions are documented in our liblab version guide.
Some SDK languages are only available in certain versions of liblab, whereas others might be available in multiple versions and you can use this option to determine which version to use.
If an SDK language is added in a later version, then setting an earlier version will default to the first version that supports that language. For example, C# is added in liblab version 2, so setting this to 1:
{
"languages": [
"csharp"
],
"languageOptions": {
"csharp": {
"liblabVersion": "1"
}
}
}
Will be the equivalent of setting it to 2.
You can read more on the supported liblab versions and the capabilities of SDKs using these versions in our liblab version guide.
githubRepoName
Supported SDK languages and versions:
TypeScript v1 TypeScript v2 Java v1 Java v2 Python v1 Python v2 C# Go PHP ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
The githubRepoName
setting sets the name of the GitHub repository for this SDK. This is used by the liblab pr
command to create a pull request for the SDK into that repo. You can read more about this in the liblab pr
section of the liblab CLI documentation.
It's also used in Java v2 SDKs to fill in scm information in the pom.xml
file, required when publishing to Maven Central.
targetBranch
Supported SDK languages and versions:
TypeScript v1 TypeScript v2 Java v1 Java v2 Python v1 Python v2 C# Go PHP ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
The targetBranch
setting sets the branch in GitHub for this SDK in the repo defined in the githubRepoName
setting. This is used by the liblab pr
command to create a pull request for the SDK into that branch. You can read more about this in the liblab pr
section of the liblab CLI documentation.
It's also used in Java SDKs to fill in scm information in the pom.xml
file, required when publishing to Maven Central.
ignoreFiles
Supported SDK languages and versions:
TypeScript v1 TypeScript v2 Java v1 Java v2 Python v1 Python v2 C# Go PHP ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
This option allows you to specify a list of files to ignore when generating the SDK. This is useful if you want to exclude files that are generated by the SDK generator. For example, if you want to completely customize the README or package manifest files.
For example, if you want to create a custom README file for your SDK that is not replaced during SDK generation, set this value to README.md
:
- TypeScript v1
- TypeScript v2
- Java v1
- Java v2
- Python v1
- Python v2
- C#
- Go
- PHP
{
...
"languageOptions": {
"typescript": {
"ignoreFiles": [
"README.md"
]
}
}
...
}
{
...
"languageOptions": {
"typescript": {
"ignoreFiles": [
"README.md"
]
}
}
...
}
{
...
"languageOptions": {
"java": {
"ignoreFiles": [
"README.md"
]
}
}
...
}
{
...
"languageOptions": {
"java": {
"ignoreFiles": [
"README.md"
]
}
}
...
}
{
...
"languageOptions": {
"python": {
"ignoreFiles": [
"README.md"
]
}
}
...
}
{
...
"languageOptions": {
"python": {
"ignoreFiles": [
"README.md"
]
}
}
...
}
{
...
"languageOptions": {
"csharp": {
"ignoreFiles": [
"README.md"
]
}
}
...
}
{
...
"languageOptions": {
"go": {
"ignoreFiles": [
"README.md"
]
}
}
...
}
{
...
"languageOptions": {
"php": {
"ignoreFiles": [
"README.md"
]
}
}
...
}
This is an array, so you can specify as many files as you need.
sdkVersion
Supported SDK languages and versions:
TypeScript v1 TypeScript v2 Java v1 Java v2 Python v1 Python v2 C# Go PHP ✅ ✅ ✅ ✅ ✅ ✅ ✅ ❌1 ❌
1 Go does not have a package manifest file for this version to be written to. This version is written to the README.md
file, and you will need to manually use it when you create a release of your SDK inside you GitHub repository.
The sdkVersion
setting sets the version of the SDK in the relevant file. For example, for Python SDKs, this is set in the pyproject.toml
file, for TypeScript this is set in the project.json
file.
This version should be using semver to ensure it is compatible with the different package managers. TypeScript has some limitations on what is supported, so any labels (such as alpha
in 0.9.3-alpha
) will be stripped out.
For example, with these options:
{
...
"languageOptions": {
"typescript": {
"sdkVersion": "1.0.0-alpha"
}
}
...
}
The TypeScript project.json
file will look like:
{
"version": "1.0.0"
}
Whereas the Python pyproject.toml
file will look like:
[project]
version = "1.0.0-alpha"
hookDependencies
Supported SDK languages and versions:
TypeScript v1 TypeScript v2 Java v1 Java v2 Python v1 Python v2 C# Go PHP ✅ ✅ ✅ ❌ ✅ ✅ ❌ ❌ ✅
When you create hooks, you can define the dependencies for those hooks in the relevant hooks folder (such as in the requirements.txt
for Python hooks). If you need to add additional dependencies, you can add them here and they will be added to the SDKs.
This should only be used if there is a reason you cannot add the dependency to the hook code directly. It is best practice to add them there.
This is an array of objects, with each object having the following options:
Option | Type | Required | Default | Description |
---|---|---|---|---|
name | string | ✅ | N/A | The name of the dependency |
version | string | ✅ | N/A | The version of the dependency |
groupId | string | ❌ | N/A | The groupId of the hook dependency for Java hooks |
name
The name
field is the name of the package that needs to be included in the dependencies. This is the same name you would use with the relevant packaging tool to install the package, such as npm install
or pip install
.
For example, to include the Python python-dotenv
package, you would use:
{
...
"languageOptions": {
"python": {
"hookDependencies": [
{
"name": "python-dotenv",
"version": "1.0.0"
}
]
}
}
...
}
version
The version
field defines the version to add to the dependencies.
For example, to include the TypeScript pad-left
package fixed at version 1.0.2 you would use:
{
...
"languageOptions": {
"typescript": {
"hookDependencies": [
{
"name": "pad-left",
"version": "1.0.2"
}
]
}
}
...
}
groupId
The groupId
setting is used for Java packages only, and allows you to define the groupId
for the hook dependency.
authors
Supported SDK languages and versions:
TypeScript v1 TypeScript v2 Java v1 Java v2 Python v1 Python v2 C# Go PHP ✅ ✅ ❌ ❌ ✅ ❌ ✅ ❌ ❌
The authors
option sets the list of authors of the SDK in the relevant package manifest. This is an array of objects containing the authors name, and optionally their email.
- TypeScript v1
- TypeScript v2
- Java v1
- Java v2
- Python v1
- Python v2
- C#
- Go
- PHP
The author is set in the package.json
file in the SDK.
For example, setting:
{
...
"languageOptions": {
"typescript": {
"authors": [
{
"name": "Llama Soda",
"email": "[email protected]"
}
]
}
}
...
}
will give a package.json
file with:
{
...
"author": "Llama Soda <[email protected]>",
...
}
Only one author is supported for TypeScript. If you set multiple authors for TypeScript, only the first one is used.
{
...
"languageOptions": {
"typescript": {
"authors": [
{
"name": "Llama Soda",
"email": "[email protected]"
}
]
}
}
...
}
This is not supported for Java v1 SDKs.
This feature is not supported on Java v2 SDKs. Use the Java specific developers
option instead.
The authors are set in the pyproject.toml
file in the SDK. For example, setting:
{
...
"languageOptions": {
"python": {
"authors": [
{
"name": "Llama Soda",
"email": "[email protected]"
},
{
"name": "Llama Boba",
"email": "[email protected]"
}
]
}
}
...
}
will give a pyproject.toml
file with:
[project]
authors = [
{ name="Llama Soda", email="[email protected]" },
{ name="Llama Boba", email="[email protected]" }
]
...
This feature is not currently supported in Python v2 SDKs.
The authors names are added to the Authors
property in the .csproj
file for the SDK as a comma separated list. Emails are not supported for C# SDKs.
For example, setting:
{
...
"languageOptions": {
"csharp": {
"authors": [
{
"name": "Exciting Soda API Team"
},
{
"name": "Exciting Soda SDK Team"
}
]
}
}
...
}
will give a .csproj
file with:
<PropertyGroup>
...
<Authors>Exciting Soda API Team, Exciting Soda SDK Team</Authors>
</PropertyGroup>
This feature is not currently supported during the Go beta.
This feature is not currently supported during the PHP beta.
Option | Type | Required | Default | Description |
---|---|---|---|---|
name | string | ✅ | N/A | The name of the author |
email | string | ❌ | N/A | The email address of the author |
name
The name
field is the name of the author.
email
The email
field defines the email address of the author. This field is optional.
homepage
Supported SDK languages and versions:
TypeScript v1 TypeScript v2 Java v1 Java v2 Python v1 Python v2 C# Go PHP ✅ ✅ ✅ ✅ ✅ ❌ ✅ ❌ ❌
The homepage
option sets the homepage of the SDK in the relevant package manifest. This needs to be a valid URL.
- TypeScript v1
- TypeScript v2
- Java v1
- Java v2
- Python v1
- Python v2
- C#
- Go
- PHP
The homepage is set in the package.json
file in the SDK. For example, setting:
{
...
"languageOptions": {
"typescript": {
"homepage": "https://exciting.soda"
}
}
...
}
will give a package.json
file with:
{
...
"homepage": "https://exciting.soda",
...
}
This feature is not currently supported during the TypeScript v2 beta.
The homepage is set in the pom.xml
file in the SDK. For example, setting:
{
...
"languageOptions": {
"java": {
"homepage": "https://exciting.soda"
}
}
...
}
will give a pom.xml
file with:
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
...
<organization>
<url>https://exciting.soda</url>
</organization>
</project>
The homepage is set in the pom.xml
file in the SDK. For example, setting:
{
...
"languageOptions": {
"java": {
"homepage": "https://exciting.soda"
}
}
...
}
will give a pom.xml
file with:
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
...
<url>https://exciting.soda</url>
</project>
The homepage is set in the pyproject.toml
file in the SDK. For example, setting:
{
...
"languageOptions": {
"python": {
"homepage": "https://exciting.soda"
}
}
...
}
will give a pyproject.toml
file with:
[project.urls]
Homepage = "https://exciting.soda"
This feature is not currently supported in Python v2 SDKs.
The authors names are added to the ProjectUrl
property in the .csproj
file for the SDK. For example, setting:
{
...
"languageOptions": {
"csharp": {
"homepage": "https://exciting.soda"
}
}
...
}
will give a .csproj
file with:
<PropertyGroup>
...
<ProjectUrl>https://exciting.soda</ProjectUrl>
</PropertyGroup>
This feature is not currently supported during the Go beta.
This feature is not currently supported during the PHP beta.
additionalConstructorParameters
Supported SDK languages and versions:
TypeScript v1 TypeScript v2 Java v1 Java v2 Python v1 Python v2 C# Go PHP ❌ ✅ ❌ ✅ ❌