Signals Notebook: How to download raw Swagger files (in YAML format) for Signals Notebook API definition

Who needs Swagger files?

If you are a developer integrating Signals Notebook APIs and using Swagger-compatible tools such as Postman, you may find it useful having the raw Swagger files that describe API definitions. Signals Notebook provides you with the Swagger UI on the web, where you can conveniently test the APIs in an interactive way. This article describes how you can retrieve the raw Swagger files, which helps you to start working with the APIs programmatically.

Where can I find the Swagger files?

The files are available in YAML format for you to download from your Signals Notebook tenant URL. Please follow the steps below.

1. As an Admin user, open Signals Configuration.
2. Open "System Settings". In the left column, select "API Key" -> "External API key"
3. In the right pane, click "Open External API Document" link. You will see the Swagger UI page opened.
4. In the Swagger UI page, just below the title "Signals Notebook APIs Document", you can find a link to the root Swagger file. (see the screenshot below)
   
5. This link above points to the location where you can download the root Swagger file. The other Swagger files that define all the APIs are also stored in the same directory. The URL should looks like the one below.

   https://<your SNB tenant domain>/docs/extapi/apidoc/v1/index.yaml?v=1.0.651-8349912836

   Then, the location you can find the Swagger files is as follows.

   https://<your SNB tenant domain>/docs/extapi/apidoc/v1/

6. As of the time of writing this article, the following URLs can be used for downloading the Swagger files that correspond to each path of the API.

   https://<your tenant URL>/docs/extapi/apidoc/v1/entities.yaml
   https://<your tenant URL>/docs/extapi/apidoc/v1/tasks.yaml
   https://<your tenant URL>/docs/extapi/apidoc/v1/stoichiometry.yaml
   https://<your tenant URL>/docs/extapi/apidoc/v1/materials.yaml
   https://<your tenant URL>/docs/extapi/apidoc/v1/scim.yaml
   https://<your tenant URL>/docs/extapi/apidoc/v1/notifications.yaml
   https://<your tenant URL>/docs/extapi/apidoc/v1/adt.yaml
   https://<your tenant URL>/docs/extapi/apidoc/v1/attributes.yaml
   https://<your tenant URL>/docs/extapi/apidoc/v1/history.yaml
   https://<your tenant URL>/docs/extapi/apidoc/v1/fragments.yaml
   https://<your tenant URL>/docs/extapi/apidoc/v1/inventory.yaml
   https://<your tenant URL>/docs/extapi/apidoc/v1/plates.yaml
   https://<your tenant URL>/docs/extapi/apidoc/v1/parallelExperiments.yaml

Note: You can find out what Swagger file names exist by looking into the root Swagger file, which you can download from the link at step #4. In the root Swagger file, there are "$ref" values that contain a Swagger file name. For example, by looking at the description about the "/entities" path, you will find "$ref" values contain "entities.yaml" as a file name. This tells you that you can download "entities.yaml" file from the location.