About the Structural API

The Tonic Structural API is a REST API that allows you perform Structural tasks.

Basic and advanced APIs

Basic API

The basic API is available with the Basic and Professional licenses.

It allows you to perform most API tasks.

However, you cannot use the basic API to:

• Configure table modes

• Configure generators

• Configure generator presets

• Configure custom sensitivity rules

• Configure subsetting

Advanced API

The advanced API requires an Enterprise license and allows you to perform all API tasks.

API versioning

Structural releases a new version of the API approximately once per quarter.

All API requests are against a specific version of the API. You include the version as a parameter in the request URL. Alternatively, you configure the version to use for all API requests.

After a version is released, no breaking changes are added to it.

Version format

Released versions

For released versions, Structural API version numbers use the following format:

vYYYY.MM.P

Where:

• YYYY is the release year

• MM is the release month

• P is the number of the patch release. The initial release of a version is 0. Patch releases do not contain any breaking changes. They are only used to fix bugs or to add other non-breaking changes such as new parameters that are not required.

For example, a release issued in July of 2023 is v2023.07.0. The first patch release on that version is v2023.07.1.

Release candidate

The current release candidate version of the API always has the version vRC.

You might use the release candidate version to work on API updates for newly released features or while using a beta version of a new feature.

Specifying the version for API requests

When you make an API request, you include the API version in the request URL.

To specify the version, use the api-version query parameter. For example, to use v2023.07.0, add api-version=v2023.07.0 .

You can specify a released version or the current release candidate.

The response also provides the API version that was used.

Configuring a default API version for requests

If you do not include the API version in your request, then Structural uses the configured default API version. The default version must be a released version. You cannot select the release candidate version as your default version.

On the System Status tab of Structural Settings view, Version in Use lists the version that is currently selected as the default. Before you select a default version, Version in Use is not set.

API Version section of the System Status tab on Structural Settings view

If you do not select a specific API version to be the default, and do not provide a version in the request, then Structural returns an error.

To select the default API version:

1. Click Select a version.

2. From the dropdown list, select the API version to use.

You cannot select the release candidate as the default API version.

To always use the latest API version, select Automatically apply latest.

Deprecating and removing API versions

Older versions of the Structural API are eventually deprecated and removed.

When a version is deprecated, the response header includes the date when the version will be removed.

When a version is removed, you cannot make requests against that version.

Backward compatibility

A new API version is not guaranteed to be backward compatible with previous versions. To use the new version, you might need to update your requests.

A patch version is always compatible with the original version that it patches.

For example, 2023.10.0 is not guaranteed to be compatible with 2023.07.0.

However, 2023.07.1 is guaranteed to be compatible with 2023.07.0.

Viewing generated API documentation

For the Structural API, generated Swagger documentation provides details about the API endpoints and models.

Self-hosted instances

For self-hosted instances, the API documentation is bundled with the instance. The API documentation is specific to that version of Structural.

The generated API documentation is located at <instance URL>/apidocs/index.html.

To display the API documentation for a self-hosted instance, click the actions menu at the top right, then select API Documentation.

Structural Cloud

For Structural Cloud, the generated API documentation is at https://app.tonic.ai/apidocs/index.html.

The API Documentation option in the actions menu is linked to that URL.

This API documentation is for the current version of Structural Cloud.

Selecting the version to view

The generated documentation includes documentation for both released versions and the release candidate.

From the version dropdown list at the top right, select the version of the documentation to display.

Dropdown list to select the version of the API to display documentation for