OpenAPI specification operations
  • 19 Sep 2022
  • 3 Minutes to read

OpenAPI specification operations


API Catalog UI provides you with an option to view and download the OpenAPI specification of an individual API Endpoint. If you want to download the OpenAPI specification for all the API endpoints in a domain or an environment, Traceable provides you GraphQL and REST APIs to achieve the same. There are three different steps to generate and download the OpenAPI specification using Traceable's APIs:

You can complete step 1 and step 2 using a GraphQL client, for example, Altair. Step 3 to download the specification can be completed using a browser or any REST API client.


Step 1 - Trigger OpenAPI specification generation

In Step 1, we trigger the OpenAPI specification generation for a domain or an environment. If you want to download the specification for an individual API Endpoint, you can do so using the Traceable Platform. For more information, see Endpoint details. This API is used only to trigger the process of OpenAPI specification generation and does not provide the generated specification. The link to download the specification is part of Step 2. As part of specification generation, you can choose to include a very high-level information about Endpoints that are under learning or you can choose to exclude them. For more information, see Options.

Endpoint URL

The Endpoint URL is - https://<traceable_public_api_url>/graphql

For example, https://api.traceable.ai/graphql

FieldcreateApiDefinition
Typemutation
Allowed role(s)
Account owner, Security Admin. For more information on Traceable roles, see Teams and roles.
AuthorizationRequires Traceable Platform token. For more information, see Public APIs.

Fetch domain ID 

You need to have domain ID to start generating the OpenAPI specification when you want to download the OpenAPI specification for a domain. Complete the following steps:

  1. Login to Traceable Platform and navigate to API Catalog > Domains
  2. Click on the domain for which you want to fetch the domain ID.
  3. The hexadecimal ID in the URL is the domain ID. For example, in the above screenshot, the domain ID would be b721093e-3870-55ca-a03c-d4fe721b6708.

Schema

You can access the schema by following the Public APIs document.

Options

The following table lists the different options.

GraphQL argumentGraphQL fieldTypeRequiredDefault behavior (if optional)Possible values and their meaning
apiDefinitionSpeclearningEndpoingStrategyEnumOptionalMENTION
  • MENTION - Use MENTION if you want to include very high-level details of the Endpoints that are being learnt as part of the specification.
  • EXCLUDE - Use EXCLUDE if you do not want to include the Endpoints that are being learnt as part of the specification.

Example request 

Following is a request example:

mutation CreateApiDefinition {
  createApiDefinition(
    apiDefinitionSpec: { format: OPEN_API_YAML, domainId: "b721093e-3870-55ca-a03c-d4fe721b6708", learningEndpoingStrategy: MENTION }
  ) {
    id
  }
}

Example response

{
  "data": {
    "getApiDefinition": {
      "id": "6f93e41b-0bc5-5787-9e07-ba085b1c5e46"
    }
  }
}
Note
Make a note of the ID returned in the response. This ID (6f93e41b-0bc5-5787-9e07-ba085b1c5e46 in the above example response) is used to view the status of the specification generation.

Step 2 - View OpenAPI specification generation status

You can use this API to view the status of OpenAPI specification generation. This API only displays the status of the specification generation and not the specification itself. However, the API response provides you with a URL to download the specification. Downloading the specification is part of Step 3. You can poll the field to view whether specification generation is a success or failure. The response displays an appropriate message. When the specification generation is successful, the response has the URL to download the specification. 

Prerequisite

You need to have the ID that was generated as part of the Step 1. For example, you can view the ID in the sample response provided in the previous section. 

Endpoint URL

The Endpoint URL is - https://<traceable_public_api_url>/graphql

For example, https://api.traceable.ai/graphql

FieldgetApiDefinition
Typequery
Allowed role(s)
Account owner, Security Admin, Developer, and Security Analyst. For more information on Traceable roles, see Teams and roles.
AuthorizationRequires Traceable Platform token. For more information, see Public APIs.

Schema

You can access the schema by following the Public APIs document. 

Example request

Following is an example request to view the status of the OpenAPI specification generation. Make sure that you use the ID that was generated when you had triggered the OpenAPI specification generation.

query GetApiDefinition {
  getApiDefinition(id: "6f93e41b-0bc5-5787-9e07-ba085b1c5e46") {
    downloadUrl
    status
    statusUpdatedTimestamp
    messages
  }
}

Example response

{
  "data": {
    "getApiDefinition": {
      "downloadUrl": "https://app.traceable.ai/rest/download?id=6f93e41b-0bc5-5787-9e07-ba085b1c5e46",
      "status": "JOB_STATUS_SUCCESS",
      "statusUpdatedTimestamp": "2022-03-11T08:54:40.902Z"
      "messages": []
    }
  }
}

Step 3 - Download the specification

You can use this API to download the generated OpenAPI specification. You can directly open the download URL that you get as part of Step 2 (see Example response) in a browser to download the specification. If any authentication is required, you would be redirected to the login page.

Endpoint URL

The Endpoint URL is - https://<traceable_url>/rest/download

For example, https://api.traceable.ai/rest/download

Endpoint Information

The following table lists the Endpoint information.

MethodGET
Response formatsA downloadable *.zip file.

Request Parameters

The following table lists the different request parameters.

NameRequired
Description
Example
id (query parameter)MandatoryOpenAPI specification ID2684a49b-d3ce-58cb-8abc-102c8be6b424

Request format

curl '<URL_from_the_previous_step>' \
--header 'Authorization: <Platform_API_Token>' \
--output <Desired_ZIP_file_name>

Following is an example request: 

curl 'https://api.traceable.ai/rest/download?id=2684a49b-d3ce-58cb-a8cb-102c8be6b424' \
--header 'Authorization: 2c3bef4f02a317fe3a09c413e4067e863f33a235f637679a21da181f224b1f8ecd6216d94019d7289625d2d5f766b80bf82ea8d663e282a5a118b26bdecd29af' \
--output open-api-spec.zip

This will download the specification in a zip file.


Was this article helpful?