Support OpenAPI Specification in API Platform

[NethmiRanasinghe]

Problem

API Platform currently allows users to create REST APIs by attaching individual resources as operations to the API create request payload. There's no way to create an API by providing a complete OpenAPI spec, or to retrieve or update that spec afterward.

In the REST API creation flow (Import API Contract, Import from URL, Design from Scratch), an API definition is generated client-side and shown in the UI, but it is never persisted.

Persisting the API definition is now required to support directly publishing APIs to the API Portal via API Platform [1].

Solution Overview

• Allow APIs to be created by including the OpenAPI Definition directly in the request payload, so the feature is also accessible via REST API alone (not just the UI flow).
• Persist the OpenAPI Definition in the DB when an API is created via Import API Contract or Import from URL.
• Introduce a new UI tab in the Management console to view, update, and delete the API Definition.
• For APIs created from scratch, allow the API Definition to be generated.

[1]. #3242

[NethmiRanasinghe]

Implementation Approach

DB Design

• Add a new table to the DB to persist the API spec.

• As discussed with @dushaniw , @malinthaprasan and @AnuGayan, API Definition is considered as an API Documentation and therefore it is stored in the same documents table along with the other Documents related to the API.

• A separate type column to filter the API spec.

• Also it was decided the API Definition will not be listed under the Documents tab.

CREATE TABLE IF NOT EXISTS api_documents (
    uuid              VARCHAR(40)  PRIMARY KEY,
    artifact_uuid     VARCHAR(40)  NOT NULL,
    organization_uuid VARCHAR(40)  NOT NULL,
    type              VARCHAR(20)  NOT NULL,
    handle            VARCHAR(40)  NOT NULL,
    display_name      VARCHAR(255) NOT NULL,
    file_name         VARCHAR(255),
    content_type      VARCHAR(100),
    content           BLOB         NOT NULL, 
    data_version      VARCHAR(20)   NOT NULL DEFAULT '1.0',
    created_by        VARCHAR(255),
    created_at        DATETIME     DEFAULT CURRENT_TIMESTAMP,
    updated_by        VARCHAR(255),
    updated_at        DATETIME     DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (artifact_uuid)     REFERENCES artifacts(uuid)      ON DELETE CASCADE,
    FOREIGN KEY (organization_uuid) REFERENCES organizations(uuid)  ON DELETE CASCADE
);

• new column content_type added to support thumbnails to be stored in the same table. Thumbnail MIME type (PNG/JPEG/SVG) can't be round-tripped. Serving back a thumbnail requires guessing the content-type from the file_name extension, which is fragile.

REST API Design

The following endpoints will be added:

Endpoint	Verb	Purpose	Payload
/rest-apis/import-openapi	POST	Create a REST API by importing an OpenAPI spec	file (OpenAPI spec), name, description, context, version, endpointUrl
/rest-apis/{restApiId}/openapi	GET	Retrieve the OpenAPI Definition of a REST API	—
/rest-apis/{restApiId}/openapi	PUT	Update the OpenAPI Definition of a REST API	OpenAPI spec (file or raw content)
/rest-apis/validate-openapi	POST	validate the OpenAPI spec	file (OpenAPI spec)

Needs Clarification

• REST design - backend endpoints to be introduced and their names ? This was discussed and finalized in the latest Design review held on 14.09.2026.
• DB table name ? This was discussed and finalized with @Thushani-Jayasekera .

[NethmiRanasinghe]

Key Design Decisions

• As discussed offline with @dushaniw and @malinthaprasan, the feature will have two sources of truth:

1. The operations property (used to generate api.yaml)

This remains the live source for API operations and operation-level policies. It is used for:

• Viewing and updating API resources, since this is where the latest operations reside (Routing page).
• Operation-level policies, since policies are stored inside each operation in the operations object.

"operations": [
  {
    "name": "getPetById",
    "description": "Find pet by ID",
    "request": {
      "method": "GET",
      "path": "/pet/{petId}",
      "policies": [
        {
          "executionCondition": "request.header.x-custom == 'enabled'",
          "name": "SET_HEADER",
          "params": {
            "key": "MyHeader",
            "value": "MyValue"
          },
          "version": "v1"
        }
      ]
    }
  }
]

2. The OpenAPI spec — schemas, request/response models, parameters, and anything the Try-out page needs. It is used for:

• The Try-out section.
• Viewing and editing the spec separately.
• Publishing to the API Portal.

🔴 It was decided in the discussion that these two sources are allowed to drift and will not always be in sync.

• When a user adds, edits, or deletes resources via the new routing UI (or the API edit page), the spec is not auto-synced. Keeping it in sync is considered the developer's responsibility.

• Even if operations were synced automatically, things like data models inside the spec can't be safely regenerated, so a partial sync would be misleading rather than helpful.

• Per-deployment spec for Try-out

To support the Try-out feature, there should be an OpenAPI spec for each deployment, since users should be able to try out operations against a specific deployment rather than against the operations in the working copy.

• To support this, @malinthaprasan and @dushaniw suggested including the API Definition in the builds table as well, so that Try-out can read the spec from there.
• Current spec in the api_artifacts table at the time of deployment should be added to the builds table and it is assumed that the user has manually updated the spec if there are any modifications.
• The column addition will be done by @dakshina99 once the decision is approved during the upcoming design review.

[NethmiRanasinghe]

Update

Following points were discussed and verified during the Design Discussion.

API creation via import-openapi

• When an API is created by importing an OpenAPI Definition, the POST call must also generate the corresponding operations in api.yaml.
• We do not generate specs in the other direction. Design from Scratch always uses POST /rest-apis, which generates operations (defaulting to /*), but leaves the API Definition empty.
• If the user wants to publish an API created from scratch, a minimal spec can be generated on the API Definition page, derived from the existing operations.

API Edit page vs. API Definition page

• Operations shown on the Resources page are loaded from operations in api.yaml, since these are the operations that reflect what's deployed to the gateway.
• Nothing is synced automatically between the two pages. Instead, the UI shows a warning when the operations and the API Definition are out of sync — this diff comparison happens on the UI side.
• The user is then asked whether they want to sync them. If they choose to, the sync is performed via POST /swagger (to update the spec from the operations) or POST /rest-apis/{id} (to update the operations from the spec), depending on the direction of sync.

Builds table

• Do not add the OpenAPI spec to the builds table.