[Proposal] Publishing APIs from Platform API to API Portal #3242

Pranavan-S · 2026-08-17T16:34:21Z

Pranavan-S
Aug 17, 2026
Collaborator

Problem Overview

Feature Ticket: #429

Design Document: Doc Link

What is the problem?

An organization builds and manages its APIs in the Management Console (backed by platform-api), but currently there is no functionality provided from the platform-api to publish the API to the API Portal.

Why now?

This is a foundational gap, as every other portal capability (search, docs, try out, subscriptions) depends on APIs actually getting published first, so api-portal can't fully serve its purpose until this exists.

Audience

We're primarily solving this for API providers who want to publish their APIs to one or more API Portals and manage that from one place seamlessly.

Problem Breakdown

We need a table to track the [published API, api-portal] entries and relevant artifact details (docs, specs, images) from the platform-api side.
We need REST endpoints on platform-api to manage the entries in the tables from [1](CRUD operations).
We need to communicate the api-portal from the platform-api, to communicate the API publishing information (we already have developed api-portal endpoints, we need to invoke them from the platform-api).

Proposed Solution

Overview

From the high-level view, this solution packs the following:

Designing DBs to persists the publication and the draft configuration details in the platform-api.
Developing REST endpoint to manage the entries in the tables.
Utilize the existing endpoints from API portal to publish the API to the portal.
Provide an intuitive UI/UX design for seamless publication of an API.

This design lets an API Provider/Publisher to:

Publish an API proxy to any connected API Portal: select one of the organization's registered portals and publish to it. Each (API, portal) pairing is tracked independently, so the same API can be published differently across multiple portals.
Configure how the API is presented in a portal such as setting its display name, version, description, production/sandbox endpoints, and thumbnail image.
Attach existing subscription plans that have already been created under an organization.
Attach existing documents that have already been created for the API artifact.
Save changes as a draft, every configuration change (details, plans, documents, definition, thumbnail, landing page) is saved into a private draft first. The draft can be reviewed, edited, or left incomplete across multiple sessions with no effect on what consumers currently see
Publishing is a separate, explicit action that promotes the draft to the live listing.
Deprecating an API removes the API from live listing, so that existing subscribers can continue to use while to new subscriptions are avoided.
Un publishing an API immediately removes the live listing from the portal entirely.

Open for discussion

Unpublish is permanent, takes any unsaved draft down with it (complete sweep across console and portal), and can be forced through if the API still has active subscribers: This decision needs to be finalized and might induce changes from the API portal side.
Publish, unpublish and deprecate each need their own separate endpoints for each API type, instead of sharing one like most of our other endpoints do. This is to gain a granular control over critical actions like publish, unpublish and deprecate.

Pranavan-S · 2026-09-09T08:30:02Z

Pranavan-S
Sep 9, 2026
Collaborator Author

Update

Adding REST Design

19 endpoints in total(16 new, 3 endpoints coming from documentation feature):

3 type-agnostic reads of the API's own content (definition, thumbnail, documents catalog) - not falls under this Feature's scope but this design depends on it.
1 type-agnostic status rollup — every portal a caller might publish to, side by side, including those with no record.
4 type-agnostic reads of the live publication (per-portal).
8 type-agnostic draft operations (GET + PUT × 4 fields: details, definition, thumbnail, landing page).
3 per-type lifecycle actions — publish, unpublish, deprecate — replicated per API type family.

Following endpoints are subject to change based on how the documentation endpoints are defined
1. /apis/{apiType}/{apiId}/definition
2. /apis/{apiType}/{apiId}/thumbnail
3. /apis/{apiType}/{apiId}/docs

Refer the trimmed version of the API contract below (tags, long descriptions, detailed component schema are stripped out to keep it short):

paths:
  /apis/{apiType}/{apiId}/definition:
    parameters:
      - $ref: '#/components/parameters/apiType'
      - $ref: '#/components/parameters/apiHandle'
    get:
      operationId: getApiDefinition
      summary: Get API definition
      security:
        - OAuth2Security: [ap:api:read]
      responses:
        '200': { $ref: '#/components/responses/DefinitionResponse' }
        '404': { $ref: '#/components/responses/NotFound' }

  /apis/{apiType}/{apiId}/thumbnail:
    parameters:
      - $ref: '#/components/parameters/apiType'
      - $ref: '#/components/parameters/apiHandle'
    get:
      operationId: getApiThumbnail
      summary: Get API thumbnail
      security:
        - OAuth2Security: [ap:api:read]
      responses:
        '200': { $ref: '#/components/responses/ThumbnailImageResponse' }
        '404': { $ref: '#/components/responses/NotFound' }

  /apis/{apiType}/{apiId}/docs:
    parameters:
      - $ref: '#/components/parameters/apiType'
      - $ref: '#/components/parameters/apiHandle'
    get:
      operationId: listApiDocs
      summary: List API documents
      security:
        - OAuth2Security: [ap:api:read]
      responses:
        '200': { content: { application/json: { schema: { $ref: '#/components/schemas/DocListResponse' } } } }
        '400': { $ref: '#/components/responses/BadRequest' }
        '404': { $ref: '#/components/responses/NotFound' }

  # --- Publications — standalone, not nested under /apis or /api-portals -----

  /api-publications:
    get:
      operationId: listApiPublications
      summary: List API publications across API Portals
      parameters:
        - $ref: '#/components/parameters/apiType-Q'
        - $ref: '#/components/parameters/apiHandle-Q'
      security:
        - OAuth2Security: [ap:api_publication:read]
      responses:
        '200': { content: { application/json: { schema: { $ref: '#/components/schemas/PublicationSummaryResponse' } } } }
        '400': { $ref: '#/components/responses/BadRequest' }
        '404': { $ref: '#/components/responses/NotFound' }

  # --- The live publication -----------------------------------------------------

  /api-portals/{apiPortalId}/apis/{apiType}/{apiId}/publication:
    parameters:
      - $ref: '#/components/parameters/apiPortalId'
      - $ref: '#/components/parameters/apiType'
      - $ref: '#/components/parameters/apiHandle'
    get:
      operationId: getApiPublication
      summary: Get API publication
      security:
        - OAuth2Security: [ap:api_portal:publication:read]
      responses:
        '200': { content: { application/json: { schema: { $ref: '#/components/schemas/Publication' } } } }
        '404': { $ref: '#/components/responses/NotFound' }

  /api-portals/{apiPortalId}/apis/{apiType}/{apiId}/publication/definition:
    parameters:
      - $ref: '#/components/parameters/apiPortalId'
      - $ref: '#/components/parameters/apiType'
      - $ref: '#/components/parameters/apiHandle'
    get:
      operationId: getApiPublicationDefinition
      summary: Get published definition
      security:
        - OAuth2Security: [ap:api_portal:publication:read]
      responses:
        '200': { $ref: '#/components/responses/DefinitionResponse' }
        '404': { $ref: '#/components/responses/NotFound' }

  /api-portals/{apiPortalId}/apis/{apiType}/{apiId}/publication/landing-page:
    parameters:
      - $ref: '#/components/parameters/apiPortalId'
      - $ref: '#/components/parameters/apiType'
      - $ref: '#/components/parameters/apiHandle'
    get:
      operationId: getApiPublicationLandingPage
      summary: Get published landing page
      security:
        - OAuth2Security: [ap:api_portal:publication:read]
      responses:
        '200': { $ref: '#/components/responses/LandingPageResponse' }
        '404': { $ref: '#/components/responses/NotFound' }

  /api-portals/{apiPortalId}/apis/{apiType}/{apiId}/publication/thumbnail:
    parameters:
      - $ref: '#/components/parameters/apiPortalId'
      - $ref: '#/components/parameters/apiType'
      - $ref: '#/components/parameters/apiHandle'
    get:
      operationId: getApiPublicationThumbnail
      summary: Get published thumbnail
      security:
        - OAuth2Security: [ap:api_portal:publication:read]
      responses:
        '200': { $ref: '#/components/responses/ThumbnailImageResponse' }
        '404': { $ref: '#/components/responses/NotFound' }

  # --- The per-portal draft ------------------------------------------------------

  /api-portals/{apiPortalId}/apis/{apiType}/{apiId}/draft:
    parameters:
      - $ref: '#/components/parameters/apiPortalId'
      - $ref: '#/components/parameters/apiType'
      - $ref: '#/components/parameters/apiHandle'
    get:
      operationId: getApiPublicationDraft
      summary: Get publication draft
      security:
        - OAuth2Security: [ap:api_portal:draft:read]
        - OAuth2Security: [ap:api_portal:draft:manage]
      responses:
        '200': { content: { application/json: { schema: { $ref: '#/components/schemas/PublicationDraftDetails' } } } }
        '404': { $ref: '#/components/responses/NotFound' }
    put:
      operationId: saveApiPublicationDraft
      summary: Save publication draft (creates the draft on first save)
      security:
        - OAuth2Security: [ap:api_portal:draft:update]
        - OAuth2Security: [ap:api_portal:draft:manage]
      requestBody:
        content: { application/json: { schema: { $ref: '#/components/schemas/PublicationDraftDetailsInput' } } }
      responses:
        '200': { content: { application/json: { schema: { $ref: '#/components/schemas/PublicationDraftDetails' } } } }
        '400': { $ref: '#/components/responses/PublicationBadRequest' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }

  /api-portals/{apiPortalId}/apis/{apiType}/{apiId}/draft/definition:
    parameters:
      - $ref: '#/components/parameters/apiPortalId'
      - $ref: '#/components/parameters/apiType'
      - $ref: '#/components/parameters/apiHandle'
    get:
      operationId: getApiPublicationDraftDefinition
      summary: Get draft definition
      security:
        - OAuth2Security: [ap:api_portal:draft:read]
        - OAuth2Security: [ap:api_portal:draft:manage]
      responses:
        '200': { $ref: '#/components/responses/DefinitionResponse' }
        '404': { $ref: '#/components/responses/NotFound' }
    put:
      operationId: saveApiPublicationDraftDefinition
      summary: Save draft definition (requires the draft to exist)
      security:
        - OAuth2Security: [ap:api_portal:draft:update]
        - OAuth2Security: [ap:api_portal:draft:manage]
      requestBody: { $ref: '#/components/requestBodies/DefinitionUpload' }
      responses:
        '204': { description: Definition saved }
        '400': { $ref: '#/components/responses/PublicationBadRequest' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }

  /api-portals/{apiPortalId}/apis/{apiType}/{apiId}/draft/landing-page:
    parameters:
      - $ref: '#/components/parameters/apiPortalId'
      - $ref: '#/components/parameters/apiType'
      - $ref: '#/components/parameters/apiHandle'
    get:
      operationId: getApiPublicationDraftLandingPage
      summary: Get draft landing page
      security:
        - OAuth2Security: [ap:api_portal:draft:read]
        - OAuth2Security: [ap:api_portal:draft:manage]
      responses:
        '200': { $ref: '#/components/responses/LandingPageResponse' }
        '404': { $ref: '#/components/responses/NotFound' }
    put:
      operationId: saveApiPublicationDraftLandingPage
      summary: Save draft landing page (Markdown; embedded raw HTML is stripped)
      security:
        - OAuth2Security: [ap:api_portal:draft:update]
        - OAuth2Security: [ap:api_portal:draft:manage]
      requestBody: { $ref: '#/components/requestBodies/LandingPageUpload' }
      responses:
        '204': { description: Landing page saved }
        '400': { $ref: '#/components/responses/PublicationBadRequest' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }

  /api-portals/{apiPortalId}/apis/{apiType}/{apiId}/draft/thumbnail:
    parameters:
      - $ref: '#/components/parameters/apiPortalId'
      - $ref: '#/components/parameters/apiType'
      - $ref: '#/components/parameters/apiHandle'
    get:
      operationId: getApiPublicationDraftThumbnail
      summary: Get draft thumbnail
      security:
        - OAuth2Security: [ap:api_portal:draft:read]
        - OAuth2Security: [ap:api_portal:draft:manage]
      responses:
        '200': { $ref: '#/components/responses/ThumbnailImageResponse' }
        '404': { $ref: '#/components/responses/NotFound' }
    put:
      operationId: saveApiPublicationDraftThumbnail
      summary: Upload draft thumbnail (PNG/JPEG, sniffed from bytes — not the declared type or file name)
      security:
        - OAuth2Security: [ap:api_portal:draft:update]
        - OAuth2Security: [ap:api_portal:draft:manage]
      requestBody:
        content: { multipart/form-data: { schema: { type: object, required: [file], properties: { file: { type: string, format: binary } } } } }
      responses:
        '204': { description: Thumbnail saved }
        '400': { $ref: '#/components/responses/PublicationBadRequest' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }

  # --- Lifecycle actions: per-type, portal-first (type pinned as a literal apiType value) --

  /api-portals/{apiPortalId}/apis/rest-api/{apiId}/publish:
    parameters:
      - $ref: '#/components/parameters/apiPortalId'
      - $ref: '#/components/parameters/apiHandle'
    post:
      operationId: publishRestApiToApiPortal
      summary: Publish the current draft (content is pushed to the portal before anything is written locally)
      security:
        - OAuth2Security: [ap:api_portal:rest_api:publish]
        - OAuth2Security: [ap:api_portal:rest_api:manage]
      responses:
        '200': { content: { application/json: { schema: { $ref: '#/components/schemas/Publication' } } } }
        '201':
          description: Listing created
          headers: { Location: { $ref: '#/components/headers/Location' } }
          content: { application/json: { schema: { $ref: '#/components/schemas/Publication' } } }
        '400': { $ref: '#/components/responses/PublicationTypeUnsupported' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/PublicationConflict' }
        '503': { $ref: '#/components/responses/PortalUnavailable' }

  /api-portals/{apiPortalId}/apis/rest-api/{apiId}/unpublish:
    parameters:
      - $ref: '#/components/parameters/apiPortalId'
      - $ref: '#/components/parameters/apiHandle'
    post:
      operationId: unpublishRestApiFromApiPortal
      summary: Remove the listing, then delete the publication and any draft (valid only when published or deprecated)
      security:
        - OAuth2Security: [ap:api_portal:rest_api:unpublish]
        - OAuth2Security: [ap:api_portal:rest_api:manage]
      responses:
        '204': { description: Listing removed }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/PublicationConflict' }
        '503': { $ref: '#/components/responses/PortalUnavailable' }

  /api-portals/{apiPortalId}/apis/rest-api/{apiId}/deprecate:
    parameters:
      - $ref: '#/components/parameters/apiPortalId'
      - $ref: '#/components/parameters/apiHandle'
    post:
      operationId: deprecateRestApiOnApiPortal
      summary: Mark the live listing deprecated — still visible, closed to new subscriptions (valid only when published)
      security:
        - OAuth2Security: [ap:api_portal:rest_api:deprecate]
        - OAuth2Security: [ap:api_portal:rest_api:manage]
      responses:
        '200': { content: { application/json: { schema: { $ref: '#/components/schemas/Publication' } } } }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/PublicationConflict' }
        '503': { $ref: '#/components/responses/PortalUnavailable' }

0 replies

Pranavan-S · 2026-09-09T08:41:20Z

Pranavan-S
Sep 9, 2026
Collaborator Author

Update

Adding DB Design

9 Tables in total (8 new tables, Table 0 is from documentation feature):

Name of Table-0 is subject to change.

#	Table	Purpose
0	artifact_documents	from the API docs feature to store definition, thumbnail, documents
1	api_publications	The live listing for one (API, portal) pairing, plus its status
2	api_publication_drafts	Draft counterpart of Table-1, without the status
3	api_publication_contents	Published definition, landing page, thumbnail
4	api_publication_draft_contents	Draft counterpart of Table-3
5	api_publication_doc_mappings	Documents selected in the live listing
6	api_publication_draft_doc_mappings	Draft counterpart of Table-5
7	api_publication_plan_mappings	Plans selected in the live listing
8	api_publication_draft_plan_mappings	Draft counterpart of Table-7

-- 0. PLACEHOLDER — pre-existing, out of scope for this design. Stores each
--    API's own content (definition, thumbnail, uploaded documents), one row
--    per content item. Shown only because tables 5/6 below take an FK
--    against it: a publication/draft doesn't copy a document, it points at
--    the row already living here.
CREATE TABLE artifact_documents ( uuid VARCHAR(40) PRIMARY KEY, organization_uuid VARCHAR(40) NOT NULL, /* ... */ );

-- 1. The live listing for one (API, portal) pairing
CREATE TABLE IF NOT EXISTS api_publications (
    uuid              VARCHAR(40)  PRIMARY KEY,
    organization_uuid VARCHAR(40)  NOT NULL,
    artifact_uuid     VARCHAR(40)  NOT NULL,
    api_portal_uuid   VARCHAR(40)  NOT NULL,
    status            VARCHAR(20)  NOT NULL DEFAULT 'PUBLISHED',  -- PUBLISHED | DEPRECATED
    display_name      VARCHAR(255) NOT NULL,
    version           VARCHAR(30)  NOT NULL DEFAULT 'v1.0',
    description       VARCHAR(1023),
    tags              BYTEA,                        -- serialized string array; no tag catalog exists
    labels             BYTEA,                        -- serialized array of API Portal label handles
    agent_visibility  VARCHAR(20)  NOT NULL DEFAULT 'VISIBLE',    -- VISIBLE | HIDDEN
    production_url    VARCHAR(255),
    sandbox_url       VARCHAR(255),
    business_owner        VARCHAR(255),              -- author-entered; omitting these nulls the portal's own columns
    business_owner_email  VARCHAR(255),
    technical_owner       VARCHAR(255),
    technical_owner_email VARCHAR(255),
    data_version      VARCHAR(20)  NOT NULL DEFAULT '1.0',
    created_by        VARCHAR(200) NOT NULL,
    created_at        TIMESTAMPTZ  DEFAULT CURRENT_TIMESTAMP,
    updated_by        VARCHAR(200) NOT NULL,
    updated_at        TIMESTAMPTZ  DEFAULT CURRENT_TIMESTAMP,
    UNIQUE (organization_uuid, artifact_uuid, api_portal_uuid),
    UNIQUE (organization_uuid, uuid),              
    FOREIGN KEY (organization_uuid) REFERENCES organizations(uuid) ON DELETE CASCADE,
    FOREIGN KEY (artifact_uuid, organization_uuid)
        REFERENCES artifacts(uuid, organization_uuid) ON DELETE CASCADE,
    FOREIGN KEY (api_portal_uuid, organization_uuid)
        REFERENCES api_portals(uuid, organization_uuid) ON DELETE CASCADE
);

-- 2. Draft counterpart of #1 (same shape, no status column)
CREATE TABLE IF NOT EXISTS api_publication_drafts (
    uuid              VARCHAR(40)  PRIMARY KEY,
    organization_uuid VARCHAR(40)  NOT NULL,
    artifact_uuid     VARCHAR(40)  NOT NULL,
    api_portal_uuid   VARCHAR(40)  NOT NULL,
    display_name      VARCHAR(255) NOT NULL,
    version           VARCHAR(30)  NOT NULL DEFAULT 'v1.0',
    description       VARCHAR(1023),
    tags              BYTEA,
    labels            BYTEA,
    agent_visibility  VARCHAR(20)  NOT NULL DEFAULT 'VISIBLE',
    production_url    VARCHAR(255),
    sandbox_url       VARCHAR(255),
    business_owner        VARCHAR(255),
    business_owner_email  VARCHAR(255),
    technical_owner       VARCHAR(255),
    technical_owner_email VARCHAR(255),
    data_version      VARCHAR(20)  NOT NULL DEFAULT '1.0',
    created_by        VARCHAR(200) NOT NULL,
    created_at        TIMESTAMPTZ  DEFAULT CURRENT_TIMESTAMP,
    updated_by        VARCHAR(200) NOT NULL,
    updated_at        TIMESTAMPTZ  DEFAULT CURRENT_TIMESTAMP,
    UNIQUE (organization_uuid, artifact_uuid, api_portal_uuid),
    UNIQUE (organization_uuid, uuid),
    FOREIGN KEY (organization_uuid) REFERENCES organizations(uuid) ON DELETE CASCADE,
    FOREIGN KEY (artifact_uuid, organization_uuid)
        REFERENCES artifacts(uuid, organization_uuid) ON DELETE CASCADE,
    FOREIGN KEY (api_portal_uuid, organization_uuid)
        REFERENCES api_portals(uuid, organization_uuid) ON DELETE CASCADE
);

-- 3. Published definition / landing page / thumbnail. Written in the same
--    transaction as the publication row.
CREATE TABLE IF NOT EXISTS api_publication_contents (
    uuid              VARCHAR(40)  PRIMARY KEY,
    organization_uuid VARCHAR(40)  NOT NULL,
    publication_uuid  VARCHAR(40)  NOT NULL,
    type              VARCHAR(20)  NOT NULL,        -- IMAGE | API_DEFINITION | MARKETING
    file_name         VARCHAR(255),                 -- API_DEFINITION: canonical name recording the serialization.
                                                     -- IMAGE: the uploader's own file name. Null for MARKETING.
    content           BYTEA        NOT NULL,
    data_version      VARCHAR(20)  NOT NULL DEFAULT '1.0',
    created_by        VARCHAR(200) NOT NULL,
    created_at        TIMESTAMPTZ  DEFAULT CURRENT_TIMESTAMP,
    updated_by        VARCHAR(200) NOT NULL,
    updated_at        TIMESTAMPTZ  DEFAULT CURRENT_TIMESTAMP,
    UNIQUE (organization_uuid, publication_uuid, type),
    FOREIGN KEY (organization_uuid) REFERENCES organizations(uuid) ON DELETE CASCADE,
    FOREIGN KEY (publication_uuid, organization_uuid)
        REFERENCES api_publications(uuid, organization_uuid) ON DELETE CASCADE
);

-- 4. Draft counterpart of #3
CREATE TABLE IF NOT EXISTS api_publication_draft_contents (
    uuid              VARCHAR(40)  PRIMARY KEY,
    organization_uuid VARCHAR(40)  NOT NULL,
    draft_uuid        VARCHAR(40)  NOT NULL,
    type              VARCHAR(20)  NOT NULL,        -- IMAGE | API_DEFINITION | MARKETING
    file_name         VARCHAR(255),
    content           BYTEA        NOT NULL,
    data_version      VARCHAR(20)  NOT NULL DEFAULT '1.0',
    created_by        VARCHAR(200) NOT NULL,
    created_at        TIMESTAMPTZ  DEFAULT CURRENT_TIMESTAMP,
    updated_by        VARCHAR(200) NOT NULL,
    updated_at        TIMESTAMPTZ  DEFAULT CURRENT_TIMESTAMP,
    UNIQUE (organization_uuid, draft_uuid, type),
    FOREIGN KEY (organization_uuid) REFERENCES organizations(uuid) ON DELETE CASCADE,
    FOREIGN KEY (draft_uuid, organization_uuid)
        REFERENCES api_publication_drafts(uuid, organization_uuid) ON DELETE CASCADE
);

-- 5. Documents selected in the live listing (pure junction table)
CREATE TABLE IF NOT EXISTS api_publication_doc_mappings (
    organization_uuid VARCHAR(40)  NOT NULL,
    publication_uuid  VARCHAR(40)  NOT NULL,
    doc_uuid          VARCHAR(40)  NOT NULL,
    created_by        VARCHAR(200) NOT NULL,
    created_at        TIMESTAMPTZ  DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (organization_uuid, publication_uuid, doc_uuid),
    FOREIGN KEY (organization_uuid) REFERENCES organizations(uuid) ON DELETE CASCADE,
    FOREIGN KEY (publication_uuid, organization_uuid)
        REFERENCES api_publications(uuid, organization_uuid) ON DELETE CASCADE,
    FOREIGN KEY (doc_uuid, organization_uuid)          -- CASCADE: a document deleted at its source is
        REFERENCES artifact_documents(uuid, organization_uuid) ON DELETE CASCADE  -- withdrawn here, never blocked
);

-- 6. Draft counterpart of #5
CREATE TABLE IF NOT EXISTS api_publication_draft_doc_mappings (
    organization_uuid VARCHAR(40)  NOT NULL,
    draft_uuid        VARCHAR(40)  NOT NULL,
    doc_uuid          VARCHAR(40)  NOT NULL,
    created_by        VARCHAR(200) NOT NULL,
    created_at        TIMESTAMPTZ  DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (organization_uuid, draft_uuid, doc_uuid),
    FOREIGN KEY (organization_uuid) REFERENCES organizations(uuid) ON DELETE CASCADE,
    FOREIGN KEY (draft_uuid, organization_uuid)
        REFERENCES api_publication_drafts(uuid, organization_uuid) ON DELETE CASCADE,
    FOREIGN KEY (doc_uuid, organization_uuid)
        REFERENCES artifact_documents(uuid, organization_uuid) ON DELETE CASCADE
);

-- 7. Plans selected in the live listing. subscription_plans has no
--    UNIQUE(organization_uuid, uuid), so this FK is single-column; the org
--    match is checked in the service layer.
CREATE TABLE IF NOT EXISTS api_publication_plan_mappings (
    organization_uuid      VARCHAR(40)  NOT NULL,
    publication_uuid       VARCHAR(40)  NOT NULL,
    subscription_plan_uuid VARCHAR(40)  NOT NULL,
    created_by             VARCHAR(200) NOT NULL,
    created_at             TIMESTAMPTZ  DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (organization_uuid, publication_uuid, subscription_plan_uuid),
    FOREIGN KEY (organization_uuid) REFERENCES organizations(uuid) ON DELETE CASCADE,
    FOREIGN KEY (publication_uuid, organization_uuid)
        REFERENCES api_publications(uuid, organization_uuid) ON DELETE CASCADE,
    FOREIGN KEY (subscription_plan_uuid)                -- RESTRICT: a plan with live subscribers can't
        REFERENCES subscription_plans(uuid) ON DELETE RESTRICT  -- silently vanish from a published listing
);

-- 8. Draft counterpart of #7
CREATE TABLE IF NOT EXISTS api_publication_draft_plan_mappings (
    organization_uuid      VARCHAR(40)  NOT NULL,
    draft_uuid             VARCHAR(40)  NOT NULL,
    subscription_plan_uuid VARCHAR(40)  NOT NULL,
    created_by             VARCHAR(200) NOT NULL,
    created_at             TIMESTAMPTZ  DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (organization_uuid, draft_uuid, subscription_plan_uuid),
    FOREIGN KEY (organization_uuid) REFERENCES organizations(uuid) ON DELETE CASCADE,
    FOREIGN KEY (draft_uuid, organization_uuid)
        REFERENCES api_publication_drafts(uuid, organization_uuid) ON DELETE CASCADE,
    FOREIGN KEY (subscription_plan_uuid)
        REFERENCES subscription_plans(uuid) ON DELETE RESTRICT
);

2 replies

Pranavan-S Sep 15, 2026
Collaborator Author

Open for Discussion

Renaming the tables to begin with artifact_... instead of api_...: to use the same tables for MCP proxies as well.

Pranavan-S Sep 15, 2026
Collaborator Author

Update

The draft tables and their counter parts are now merged.

#	Table	Purpose
0	api_documents	API's own definition, thumbnail, documents (outside this scope)
1	api_publications	One (API, portal) pairing
2	api_publication_contents	Definition, landing page, thumbnail (for a draft / live)
3	api_publication_doc_mappings	Documents selected (for a draft / live)
4	api_publication_plan_mappings	Plans selected (for a draft / live)

-- 0. Not part of this design. An API's own definition,
--    thumbnail and documents, one row per item. Referenced by table 3 below.
CREATE TABLE api_documents ( uuid VARCHAR(40) PRIMARY KEY, organization_uuid VARCHAR(40) NOT NULL, /* ... */ );

-- 1. One (API, portal) pairing's draft and/or live row, is_draft-discriminated.
CREATE TABLE IF NOT EXISTS api_publications (
    uuid              VARCHAR(40)  PRIMARY KEY,
    organization_uuid VARCHAR(40)  NOT NULL,
    artifact_uuid     VARCHAR(40)  NOT NULL,
    api_portal_uuid   VARCHAR(40)  NOT NULL,
    is_draft          SMALLINT     NOT NULL DEFAULT 0,  -- 0 = live row, 1 = draft row
    status            VARCHAR(20),                       -- PUBLISHED | DEPRECATED; set only when is_draft = 0
    display_name      VARCHAR(255) NOT NULL,
    version           VARCHAR(30)  NOT NULL,
    description       VARCHAR(1023),
    tags              BYTEA,                        -- serialized string array
    labels             BYTEA,                        -- serialized array of API Portal label handles
    agent_visibility  VARCHAR(20)  NOT NULL DEFAULT 'VISIBLE',    -- VISIBLE | HIDDEN
    production_url    VARCHAR(255),
    sandbox_url       VARCHAR(255),
    business_owner        VARCHAR(255),
    business_owner_email  VARCHAR(255),
    technical_owner       VARCHAR(255),
    technical_owner_email VARCHAR(255),
    data_version      VARCHAR(20)  NOT NULL DEFAULT '1.0',
    created_by        VARCHAR(200) NOT NULL,
    created_at        TIMESTAMPTZ  DEFAULT CURRENT_TIMESTAMP,
    updated_by        VARCHAR(200) NOT NULL,
    updated_at        TIMESTAMPTZ  DEFAULT CURRENT_TIMESTAMP,
    UNIQUE (organization_uuid, artifact_uuid, api_portal_uuid, is_draft),
    UNIQUE (organization_uuid, uuid),
    FOREIGN KEY (organization_uuid) REFERENCES organizations(uuid) ON DELETE CASCADE,
    FOREIGN KEY (artifact_uuid, organization_uuid)
        REFERENCES artifacts(uuid, organization_uuid) ON DELETE CASCADE,
    FOREIGN KEY (api_portal_uuid, organization_uuid)
        REFERENCES api_portals(uuid, organization_uuid) ON DELETE CASCADE
);

-- 2. Definition / landing page / thumbnail, for a draft or live api_publications row.
CREATE TABLE IF NOT EXISTS api_publication_contents (
    uuid              VARCHAR(40)  PRIMARY KEY,
    organization_uuid VARCHAR(40)  NOT NULL,
    publication_uuid  VARCHAR(40)  NOT NULL,
    type              VARCHAR(20)  NOT NULL,        -- IMAGE | API_DEFINITION | MARKETING
    file_name         VARCHAR(255),                 -- API_DEFINITION: canonical name recording the serialization.
                                                     -- IMAGE: the uploader's own file name. Null for MARKETING.
    content_type      VARCHAR(100),                 -- sniffed at upload, not the client's declared type. Null for MARKETING.
    content           BYTEA        NOT NULL,
    data_version      VARCHAR(20)  NOT NULL DEFAULT '1.0',
    created_by        VARCHAR(200),
    created_at        TIMESTAMPTZ  DEFAULT CURRENT_TIMESTAMP,
    updated_by        VARCHAR(200),
    updated_at        TIMESTAMPTZ  DEFAULT CURRENT_TIMESTAMP,
    UNIQUE (organization_uuid, publication_uuid, type),
    FOREIGN KEY (organization_uuid) REFERENCES organizations(uuid) ON DELETE CASCADE,
    FOREIGN KEY (publication_uuid, organization_uuid)
        REFERENCES api_publications(uuid, organization_uuid) ON DELETE CASCADE
);

-- 3. Documents selected, for a draft or live api_publications row (pure junction table)
CREATE TABLE IF NOT EXISTS api_publication_doc_mappings (
    organization_uuid VARCHAR(40)  NOT NULL,
    publication_uuid  VARCHAR(40)  NOT NULL,
    doc_uuid          VARCHAR(40)  NOT NULL,
    created_by        VARCHAR(200) NOT NULL,
    created_at        TIMESTAMPTZ  DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (organization_uuid, publication_uuid, doc_uuid),
    FOREIGN KEY (organization_uuid) REFERENCES organizations(uuid) ON DELETE CASCADE,
    FOREIGN KEY (publication_uuid, organization_uuid)
        REFERENCES api_publications(uuid, organization_uuid) ON DELETE CASCADE,
    -- api_documents has no UNIQUE(organization_uuid, uuid) — single-column FK
    FOREIGN KEY (doc_uuid) REFERENCES api_documents(uuid) ON DELETE CASCADE
);

-- 4. Plans selected, for a draft or live api_publications row.
CREATE TABLE IF NOT EXISTS api_publication_plan_mappings (
    organization_uuid      VARCHAR(40)  NOT NULL,
    publication_uuid       VARCHAR(40)  NOT NULL,
    subscription_plan_uuid VARCHAR(40)  NOT NULL,
    created_by             VARCHAR(200) NOT NULL,
    created_at             TIMESTAMPTZ  DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (organization_uuid, publication_uuid, subscription_plan_uuid),
    FOREIGN KEY (organization_uuid) REFERENCES organizations(uuid) ON DELETE CASCADE,
    FOREIGN KEY (publication_uuid, organization_uuid)
        REFERENCES api_publications(uuid, organization_uuid) ON DELETE CASCADE,
    FOREIGN KEY (subscription_plan_uuid)
        REFERENCES subscription_plans(uuid) ON DELETE RESTRICT
);

Navigation Menu

[Proposal] Publishing APIs from Platform API to API Portal #3242

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 2 comments 2 replies

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Select a reply

Uh oh!

[Proposal] Publishing APIs from Platform API to API Portal #3242

Uh oh!

Uh oh!

Pranavan-S Aug 17, 2026 Collaborator

Problem Overview

What is the problem?

Why now?

Audience

Problem Breakdown

Proposed Solution

Overview

From the high-level view, this solution packs the following:

This design lets an API Provider/Publisher to:

Open for discussion

Replies: 2 comments · 2 replies

Uh oh!

Uh oh!

Pranavan-S Sep 9, 2026 Collaborator Author

Update

Adding REST Design

Uh oh!

Uh oh!

Pranavan-S Sep 9, 2026 Collaborator Author

Update

Adding DB Design

Uh oh!

Pranavan-S Sep 15, 2026 Collaborator Author

Open for Discussion

Uh oh!

Uh oh!

Pranavan-S Sep 15, 2026 Collaborator Author

Update

Pranavan-S
Aug 17, 2026
Collaborator

Replies: 2 comments 2 replies

Pranavan-S
Sep 9, 2026
Collaborator Author

Pranavan-S
Sep 9, 2026
Collaborator Author

Pranavan-S Sep 15, 2026
Collaborator Author

Pranavan-S Sep 15, 2026
Collaborator Author