Automatic Documentation Synchronization (CI/CD)

Is it possible to update your documentation programmatically? Yes, Apiable provides a Platform API that may be used in conjunction with our Webhooks to retrieve, create, and update documentation programmatically.

What is CI/CD?

API Specifications in the context of CI/CD refer to the practice of continuously integrating and deploying API documentation and definitions as they evolve.

Continuous Integration (CI) for API Specifications involves regularly updating the API definitions as endpoints are added, modified, or deprecated, automatically validating them against predefined standards, and testing their interoperability with other systems.

Continuous Deployment/Delivery (CD) for these specifications ensures that the latest, validated version of the API documentation is always available to developers, partners, and stakeholders without manual intervention. This approach ensures that API consumers have up-to-date information, fostering consistent integration, rapid feedback loops, and high-quality API interactions.

Please contact us for access to the Platform APIs.

Here's a guide on how to use these endpoints effectively:

1. Retrieve Documentation

Get Plan-Level Documentation by Plan ID

Endpoint: GET /api/plans/{id}/docs
Description: Fetches all plan-level documentation associated with a specified plan ID.
Parameters:
- id (path) - The ID of the plan.
Response: Returns a list of plan-level documentation for the specified plan.

Get API-Level Documentation by API Integration ID and Plan ID

Endpoint: GET /api/plans/{id}/apis/{integrationId}/docs
Description: Fetches all API-level documentation for APIs specified by the API integration ID within a plan.
Parameters:
- id (path) - The ID of the plan.
- integrationId (path) - The integration ID of the API.
Response: Returns a list of API-level documentation for the specified APIs in the plan.

2. Create Documentation

Create Plan-Level Documentation

Endpoint: POST /api/plans/{id}/docs
Description: Creates a new plan-level documentation entry for a specified plan.
Parameters:
- id (path) - The ID of the plan.
Request Body:
- A JSON object representing the documentation details.
Response: Returns the created documentation.

Create API-Level Documentation by API Integration ID and Plan ID

Endpoint: POST /api/plans/{id}/apis/{integrationId}/docs
Description: Creates new API-level documentation for APIs specified by the API integration ID within a plan.
Parameters:
- id (path) - The ID of the plan.
- integrationId (path) - The integration ID of the API.
Request Body:
- A JSON object representing the documentation details.
Response: Returns the created documentation.

3. Update Documentation

Update Plan-Level Documentation by Plan ID and Documentation ID

Endpoint: PATCH /api/plans/{id}/docs/{docId}
Description: Updates an existing plan-level documentation entry.
Parameters:
- id (path) - The ID of the plan.
- docId (path) - The ID of the documentation.
Request Body:
- An array of JSON patch operations to update the documentation.
Response: Returns the updated documentation.

Update API-Level Documentation by API Integration ID and Documentation ID

Endpoint: PATCH /api/plans/{id}/apis/{integrationId}/docs/{docId}
Description: Updates an existing API-level documentation entry.
Parameters:
- id (path) - The ID of the plan.
- integrationId (path) - The integration ID of the API.
- docId (path) - The ID of the documentation.
Request Body:
- An array of JSON patch operations to update the documentation.
Response: Returns the updated documentation.

Example Request and Response

Retrieve Plan-Level Documentation

Request:

httpCopy codeGET /api/plans/{id}/docs

Response:

[
  {
    "id": "doc123",
    "name": "Plan Documentation",
    "url": "http://example.com/docs",
    "version": "v1.0",
    "status": ["active"],
    "order": 1,
    "active": true,
    "visible": true,
    "retrievalType": "MANUAL",
    "synced": "2024-05-23T12:00:00Z",
    "planId": "plan123",
    "planDocLevel": "PLAN"
  }
]

Create API-Level Documentation

Request:

POST /api/plans/{id}/apis/{integrationId}/docs
Content-Type: application/json

{
  "id": "doc123",
  "name": "API Documentation",
  "url": "http://example.com/docs/api",
  "version": "v1.0",
  "status": ["active"],
  "order": 1,
  "active": true,
  "visible": true,
  "retrievalType": "MANUAL"
}

Response:

{
  "id": "doc123",
  "name": "API Documentation",
  "url": "http://example.com/docs/api",
  "version": "v1.0",
  "status": ["active"],
  "order": 1,
  "active": true,
  "visible": true,
  "retrievalType": "MANUAL",
  "synced": "2024-05-23T12:00:00Z",
  "planId": "plan123",
  "apiIntegrationId": "api123",
  "planDocLevel": "API"
}