Ctrlk
Sign UpGet a DemoContact Us
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Managing Documentation using APIs

API Documentation in Traceable refers to specifications that describe your APIs. Traceable supports the following documentation types:

  • OpenAPI specs

  • Postman Collections

  • Postman Environments

  • GraphQL schemas

  • WSDLs

You can manage these specifications using the following API operations to automate management, without using the Traceable platform user interface:

  • Upload — Add new documentation (spec file) and trigger discovery or naming rules, optionally.

  • Re-upload — Replace an existing spec file with a new version using the same spec ID and path.

  • Update — Modify the metadata, such as name and discovery flags, for an existing API documentation without changing the file.

  • Delete — Permanently remove the API documentation and its associated metadata.

For more information on performing these operations, see API Documentation Operations.

Traceable provides all operations except deletion through the Upload REST API. Deletion requires a GraphQL mutation followed by a REST API call.

What will you learn in this topic?

By the end of this topic, you will understand:

  • The supported operations on the API documentation files.

  • The sample API calls to upload, re-upload, update, and delete the API documentation files.

  • The limitations and best practices associated with the above operations.

Before you begin

Make a note of the following before you proceed with the operations:

  • Make sure you have the Traceable platform API token for authenticated access. For more information, see Public APIs.

  • Make sure you have the spec file you wish to upload.

  • Make sure you have a unique path for each spec.

  • (For re-upload, update, and delete operations only) Make sure you have the ID of the spec you wish to operate on.

API Documentation Operations

The following sections highlight the details for performing the available operations on your spec files.

API URL

Headers

Form-data

  • uploadConfiguration — The JSON metadata describing the operation.

  • <configKey> — You must attach the actual spec file. The key must match the configKey in the configuration.

Spec Types

The following spec types are supported in the operations:

  • OpenAPI specs — SPEC_TYPE_OPEN_API_SPEC

  • Postman Collections — SPEC_TYPE_POSTMAN_COLLECTION

  • Postman Environments — SPEC_TYPE_POSTMAN_ENVIRONMENT

  • GraphQL schemas — SPEC_TYPE_GRAPHQL_SCHEMA

  • WSDLs — SPEC_TYPE_WSDL

Upload API Documentation

This operation allows you to add new API documentation to your Traceable account. Traceable supports uploading OpenAPI, Postman, GraphQL, or WSDL specs. Optionally, you can enable API discovery and naming for the specs.

Sample Upload Configuration

In the example configuration below, you upload two API documentation files (GraphQL schema and OpenAPI spec) using the file_0 and file_1 config keys. You must upload the spec files to the corresponding config keys in the form-data section of your REST API client.

Sample Response

In the above response, the docId refers to the specId generated for the uploaded documentation. You can use this spec ID to re-upload, update, and delete the API documentation.

Re-upload API Documentation

You can use this operation to replace an existing file with a new version. You can re-upload a file using the specId or specPath. Upon re-upload, Traceable deletes the existing file and uploads the updated one to the platform.

Sample Re-upload Configuration

Sample Response

Update API Documentation

You can use this operation to modify the metadata of an existing API documentation; however, you must include the file in the request, even if it has no changes.

Sample Update Configuration

Sample Response

Delete API Documentation

This operation can permanently delete API documentation from your Traceable account. Deletion is a two-step process:

  1. Removing the spec configuration using GraphQL

  2. Deleting the file using the REST API

Traceable allows the deletion of API documentation on a one-by-one basis, meaning you cannot delete multiple documents in a single operation. This ensures that each deletion is intentional and minimizes the risk of accidentally removing the wrong documentation.

Step 1 — Removing the Spec Configuration using GraphQL

Sample API Request

Sample API Response

If the above response contains ”success”: true, complete the step below.

Step 2 — Deleting the File using REST API

Method Type — DELETE

URL — https://app-dev.traceable.ai/rest/v1/delete/documentation/openapi

Content-Type — application/json

Sample API Request

Sample API Response

PreviousDocumentation and Inspector
Next(Beta) Unified API Inventory

Last updated

Was this helpful?