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.
Note
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
POST https://api.traceable.ai/rest/uploadHeaders
Content-Type: multipart/form-data
Authorization: Bearer <platform-token> //Replace the <platform-token> placeholder with the token from your Traceable accountForm-data
uploadConfiguration— The JSON metadata describing the operation.<configKey>— You must attach the actual spec file. The key must match theconfigKeyin the configuration.
Spec Types
The following spec types are supported in the operations:
OpenAPI specs —
SPEC_TYPE_OPEN_API_SPECPostman Collections —
SPEC_TYPE_POSTMAN_COLLECTIONPostman Environments —
SPEC_TYPE_POSTMAN_ENVIRONMENTGraphQL schemas —
SPEC_TYPE_GRAPHQL_SCHEMAWSDLs —
SPEC_TYPE_WSDL
Upload API Documentation
This operation can 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.
{
"uploadOperation": [ //List of upload operations. Multiple specs can be uploaded in one call.
{
"apiDocumentUploadOperation": { //First spec upload
"name": "graphql_schema.graphql", //Name of the file to be uploaded
"specPath": "/development/OAS/graphql_schema.graphql", //Path of the file on disk
"specType": "SPEC_TYPE_GRAPHQL_SCHEMA", // Type of specification (GraphQL schema in this case)
"postUploadOperations": [], //Optional operations to trigger after upload
"configKey": "file_0", //Unique identifier to map this file in form-data
"apiNamingEnabled": false, //Whether or not API naming rules should be generated
"apiDiscoveryEnabledV2": false. //Whether or not API discovery should run after upload
}
},
{
"apiDocumentUploadOperation": {
"name": "bare-min.json",
"specPath": "/development/OAS/bare-min.json",
"specType": "SPEC_TYPE_OPEN_API_SPEC",
"postUploadOperations": [],
"configKey": "file_1",
"apiNamingEnabled": false,
"apiDiscoveryEnabledV2": false
}
}
]
}Sample Response
[
{
"docId": "ec262345-643d-4539-870f-02c123456c96",
"jobIds": [],
"messages": [],
"uploadStatus": "PARSING_SUCCESSFUL"
},
{
"docId": "3e789b70-be64-4b7c-8ab9-56bf123ffa34",
"jobIds": [],
"messages": [],
"uploadStatus": "PARSING_SUCCESSFUL"
}
]Note
In the above response, the
docIdrefers to thespecIdgenerated 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
{
"uploadOperation": [
{
"apiDocumentUploadOperation": {
"specId": "ec262335-643d-4539-870f-02c418993c96", //The docId corresponding to the spec
"name": "graphql_schema.graphql", //Name of the file to be re-uploaded
"specPath": "/development/OAS/graphql_schema.graphql", //Path of the file on disk
"specType": "SPEC_TYPE_GRAPHQL_SCHEMA", // Type of specification (GraphQL schema in this case)
"postUploadOperations": [], //Optional operations to trigger after upload
"configKey": "file_0", //Unique identifier to map this file in form-data
"apiNamingEnabled": false, //Whether or not API naming rules should be generated
"apiDiscoveryEnabledV2": false //Whether or not API discovery should run after upload
}
}
]
}Sample Response
[
{
"docId": "ec262335-643d-4539-870f-02c418993c96",
"jobIds": [],
"messages": [],
"uploadStatus": "PARSING_SUCCESSFUL"
}
]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
{
"uploadOperation": [
{
"apiDocumentUploadOperation": {
"specId": "3e882b70-be64-4b7c-8ab9-59bf958ffa34", //The docId corresponding to the spec
"name": "bare-minimum-spec-1.json", //Name of the file to be updated
"specPath": "/development/OAS/bare-min.json", //Path of the file on disk
"specType": "SPEC_TYPE_OPEN_API_SPEC", // Type of specification (Open API spec in this case)
"postUploadOperations": [], //Optional operations to trigger after update
"configKey": "file_0", //Unique identifier to map this file in form-data
"apiNamingEnabled": true, //Whether or not API naming rules should be generated
"apiDiscoveryEnabledV2": false //Whether or not API discovery should run after update
}
}
]
}Sample Response
[
{
"docId": "3e882b70-be64-4b7c-8ab9-59bf958ffa34",
"jobIds": [],
"messages": [],
"uploadStatus": "PARSING_SUCCESSFUL"
}
]Delete API Documentation
This operation can permanently delete API documentation from your Traceable account. Deletion is a two-step process:
Note
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
mutation {
deleteApiSpec(input: { id: "3e123b70-be65-4b5c-8ab9-59bf987ffa34" }) {
success
}
}Sample API Response
[
{
"data": {
"deleteApiSpec": {
"success": true
}
}
}
]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
{
"docId": "3e876b70-be65-4b7c-8ab9-59bf987ffa34"
}Sample API Response
{
"success": true
}