Overview

The Fabric Services System includes an HTTP REST API to support software integration. By using the REST API, you can write your own software that can configure any feature of the Fabric Services System.

Detailed information about all of the individual API calls is available in the OpenAPI (v2) format, also referred to as Swagger documentation. You can download Swagger YAML files from your Fabric Services System deployment, from the same location as the Reference API documentation.

You can then use these files within your own tools that can work with the standard OpenAPI specifications.

Reference documentation

Within the Fabric Services System GUI you can find detailed API documentation for each of the services that exposes an API.

When the Fabric Services System is installed, this API GUI is available at the following URL: 
https://fss.domain.tld/apidocs
where fss.domain.tld is your local installation FQDN
When you access the API GUI, the API Documentation page displays:
Figure 1. Swagger documentation in the Fabric Services System

The API GUI contains a list of the services on the left. Click on any of those services to display the Swagger (or OpenAPI) documentation.

Click the expand icon for an individual API call to see details for that call, including usage, parameter details, and a tool for issuing a sample call.

The download button allows you to download the Swagger YAML file for the selected service. You can use this file with any tools that are compatible with the OpenAPI standard. The Fabric Services System uses the OpenAPI v2 specifications format.

In addition to the reference API documentation, the same page in the Fabric Services System UI also provides a list of all the services deployed in the Fabric Services System application and the versions of each of these services. You can access this information by clicking SYSTEM VERSIONS.

Downloading the full OpenAPI definitions

You can download the OpenAPI definitions for all the services in a single file. This file can be downloaded in either YAML or JSON format using one of the following URLs:
  • YAML: https://fss.domain.tld/rest/about/swagger.yaml
  • JSON: https://fss.domain.tld/rest/about/swagger.json

URL endpoints

The Fabric Services System REST API URL path has the following format: 
https://fss.domain.tld/rest/<service>/api/<version>

where <version> stands for the major release number of the API (such as 1)

POST https://fss.domain.tld/rest/intentmgr/api/v1/queueItems/384258893435371520/deploy

Supported REST API versions

You can determine which versions of an API call are available for a specific deployment of the Fabric Services System by performing an unauthenticated HTTP GET request to the https://fss.domain.tld/rest/about/version URI:

# curl -s https://fss.domain.tld/rest/about/version | jq
{
  "fss": {
    "gitCommit": "v22.4.1-1462"
  },
  "fss-alarmmgr": {
    "gitCommit": "v22.4.1-1462-gca271333",
    "builtDate": "2022-03-23T05:24:14+00:00",
    "gitBranch": "22_4_1",
    "appName": "fss-alarmmgr",
    "apiVersions": [
      {
        "version": "v1",
        "status": "CURRENT",
        "baseURL": "fss.domain.tld/rest",
        "swaggerDoc": "fss.domain.tld/rest/alarmmgr/v1/docs/swagger.yaml"
      }
    ]
  },
  "fss-auth": {
    "gitCommit": "v22.4.1-1462-gca271333",
    "builtDate": "2022-03-23T05:15:55+00:00",
    "gitBranch": "22_4_1",
    "appName": "fss-auth",
    "apiVersions": [
      {
        "version": "v1",
        "status": "CURRENT",
        "baseURL": "fss.domain.tld/rest",
        "swaggerDoc": "fss.domain.tld/rest/auth/v1/docs/swagger.yaml"
      }
    ]
  },
...

All services and components of the Fabric Services System display in the resulting list. Only those that have an apiVersions attribute actually provide an API service.

API version strategy and backward compatibility

The Fabric Services System is composed of multiple individual applications or services. Each of these services has its own API with its own API version. While most of the services use the same latest API version, it is important to keep track of API version changes.

For each service, at least two versions are always available unless a service is using version 1 for its API. The older version is available for customers upgrading from an older version to ensure that their scripts, tools, and integrations can continue functioning on the old API after the upgrade and before they are updated to the new API.

As soon as a new API version is introduced for that service, all new functionality for the service is available only on the new API version. The older API version can only be used for the older functionality.

The platform also guarantees backward compatibility within the same version of the API. This strategy allows for the creation of scripts, tools and integrations using the same API version across multiple releases, without having to adapt them every time the platform is upgraded.
Note: Between versions of the API, backward compatibility can sometimes break when there is a need for significant changes. When upgrading the scripts, tools, and integration to use the new API, investigate and understand the impact of these changes and act accordingly.

Using the UI to inspect API calls

The Fabric Services System UI is a graphical layer that uses the API directly. You can use it to better understand the workflow and API calls that are getting executed when taking specific actions in the UI.

You can use the Web Developer tools, specifically the Network tab of the tools, to see each individual API call that is executed. You can inspect the request and response data, including the headers for each API call.