OpenAPI specification operations
  • 06 Sep 2024
  • 5 Minutes to read
  • PDF

OpenAPI specification operations

  • PDF

Article summary

API Catalog allows you to view and download the OpenAPI specification of an individual API Endpoint. Traceable provides GraphQL and REST APIs for downloading the OpenAPI specification for all the API endpoints under a domain, environment, service, or label. There are three different steps to generate and download the OpenAPI specification using Traceable's APIs:

You can complete steps 1 and 2 using a GraphQL client, such as Altair. Step 3, downloading the specification, can be completed using a browser or any REST API client.


Step 1 - Trigger OpenAPI specification generation

In this step, we trigger the OpenAPI specification generation for a domain, environment, service, or label. If you wish 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 very high-level information about Endpoints that are under learning or 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

Field

createApiDefinition

Type

mutation

Allowed role(s)


Account owner, Security Admin, and Security Analyst. For more information on Traceable roles, see Teams and roles.

Authorization

Requires Traceable Platform token. For more information, see Public APIs.

Retrieve credentials

You must have either of the following credentials to start generating the OpenAPI specification for a domain, environment, service, or label:

  • Domain ID — When you want to generate the specification for all the API endpoints under a domain.

  • Service ID — When you want to generate the specification for all the API endpoints under a service.

  • Label Name(s) — When you want to generate the specification for all the API endpoints with one or more labels.

  • Environment Name — When you want to generate the specification for all the API endpoints under an environment.

Refer to the following sections for the steps to retrieve these credentials.

Domain ID

Complete the following steps to retrieve the domain ID:

  1. Log in to the Traceable Platform and navigate to Catalog Inventory → Domains tab. 

  2. Click the domain for which you want to retrieve the domain ID.

  3. Copy the domain ID (hexadecimal ID) from the URL. For example, in the above screenshot, the domain ID is 0267a887-5c8d-57b5-a08e-41cca8ec5196.

Service ID

Complete the following steps to retrieve the service ID:

  1. Log in to the Traceable Platform and navigate to Catalog Inventory → Services tab.

  2. Click the service for which you want to retrieve the service ID.

  3. Copy the service ID (hexadecimal ID) from the URL. For example, in the above screenshot, the service ID is 837ce000-71fd-3335-b709-7486c7525949.

Label Name(s)

You can generate the specification for one or more labels. To generate the specification for multiple labels, you must specify the label names within square brackets, with each label name separated by a comma. See Examples.

Complete the following steps to retrieve the label name(s):

  1. Log in to the Traceable platform and navigate to SettingsLabel Management Labels tab.

  2. Copy the label name(s) you want to generate the specification for.

Environment

Complete the following steps to retrieve the environment name:

  1. Log in to the Traceable platform and navigate to Catalog.

  2. Copy the environment name from the Environments drop-down in the page’s top right corner.

Schema

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

Options

The following table lists the different options.

GraphQL argument

GraphQL field

Type

Required

Default behavior (if optional)

Possible values and their meaning

apiDefinitionSpec

learningEndpointStrategy

Enum

Optional

MENTION

  • MENTION - Use MENTION if you want to include high-level details of the Endpoints that are being learned as part of the specification.

  • EXCLUDE - Use EXCLUDE if you do not wish to include the Endpoints that are being learned as part of the specification.

Examples

The following are some sample requests and responses you can refer to for generating the OpenAPI specification. You can expand the sections according to your requirements.

Domains

Example request

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

Example response

{
  "data": {
    "getApiDefinition": {
      "id": "6f93e41b-0bc5-5787-9e07-ba085b1c5e46"
    }
  }
}

Services

Example request

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

Example response

{
  "data": {
    "getApiDefinition": {
      "id": "6f93e41b-0bc5-5787-9e07-ba085b1c5e46"
    }
  }
}

Labels

Example request

mutation CreateApiDefinition {
  createApiDefinition(
    apiDefinitionSpec: { format: OPEN_API_YAML, labels: ["label1", "label2", "label3"] }
  ) {
    id
  }
}

Example response

{
  "data": {
    "getApiDefinition": {
      "id": "6f93e41b-0bc5-5787-9e07-ba085b1c5e46"
    }
  }
}

Environment

Example request

mutation CreateApiDefinition {
  createApiDefinition(
    apiDefinitionSpec: { format: OPEN_API_YAML, environment: "environment_name" }
  ) {
    id
  }
}

Example response

{
  "data": {
    "getApiDefinition": {
      "id": "6f93e41b-0bc5-5787-9e07-ba085b1c5e46"
    }
  }
}

Note

Make a note of the ID returned in the response. It 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

Field

getApiDefinition

Type

query

Allowed role(s)


Account owner, Security Admin, Developer, and Security Analyst. For more information on Traceable roles, see Teams and roles.

Authorization

Requires 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.

Method

GET

Response formats

A downloadable *.zip file.

Request Parameters

The following table lists the different request parameters.

Name

Required


Description


Example


id (query parameter)

Mandatory

OpenAPI specification ID

2684a49b-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?

What's Next