[Proposal] API Artifact Directory Structure for API Platform

[Piumal1999]

<Check the next comment for the updated structure>

Requirement

• A directory/content structure for a single API that can also be used for importing into the API platform.
• A devportal-specific API artifact structure to be published to the standalone gateway.
  • The directory must contain all the necessary details for a dev portal API.
  • The structure should be intuitive and clear for a standalone dev portal user.
  • The structure should not conflict with or be confusing relative to the content in the main API project (e.g., naming conventions).

Main use cases

• A user importing an API into the platform.
• A user publishing the API to a dev portal through the management portal (In this scenario, the dev portal artifact is generated internally in the API platform).
• A user publishing an API to the dev portal using curl or a CLI tool (the user creates the artifact or uses a generated artifact). This also applies to users who use the dev portal standalone without the API platform control plane.

---

Directory Structure

MyAPI/
├── config.yaml
├── api.yaml
├── api-definition.yaml
├── docs/
│   ├── readme.md
│   └── internal-doc.md
├── tests/
└── devportals/
    ├── devportal-d1/
    │   ├── devportal-api.yaml
    │   ├── devportal-api-definition.yaml
    │   ├── docs/
    │   │   └── README.md
    │   └── webcontent/
    │       ├── api-icon.png
    │       ├── api-content.hbs
    │       └── landingpage.css
    └── devportal-2/
        └── ...

---

Root-Level Files and Directories

• config.yaml: Defines the overall structure of the API artifact. It contains paths and directory mappings (OpenAPI, docs, tests, etc.) and includes deployment-specific configurations. It may also include Governance rulesets which can be used in design time.

  Example:

  openapi: ./api-definition.yaml
  wso2Artifact: ./api.yaml
  docsFolder: ./docs
  testsFolder: ./tests
  
  goverananceRulesets:
    - name: OWASP Top 10
      sourceFolder: <link>
      fileName: owasp_top_10.yaml
      rulesetContentPath: rulesetContent
  
  deployments:
    - name: gateway-1a
      key1: value1
      key2: value2
      # gateway-specific properties
    - name: gateway-2b
      ...

• api.yaml: Contains API metadata, policies, subscription plans, and other configurations. This file may contain attributes that are not part of the APIDeploymentYAML structure [1] . When deploying an API, this file is processed to retain only the data required by the gateway. Gateway-specific configuration properties are then applied, and a new .yaml file is generated and used for deployment.

• api-definition.yaml: Contains the OpenAPI specification.

• docs/: Contains documentation to be displayed in the management portal.

• tests/: Contains test-related files.

• devportals/: Directory contains artifacts for different developer portals. Since an API can be deployed to multiple gateways with different attributes, separate dev portal configurations are maintained under this directory.

---

Dev Portals Directory

For each dev portal, we have:

• devportal-api.yaml: Contains properties required by the developer portal and the paths to the related files.

• devportal-api-definition.yaml: Contains the OpenAPI specification. This may differ from the root-level api-definition.yaml.

• docs/: Contains documents displayed in the developer portal. Currently only .md files are supported in bijira implementation. All files in this directory will be automatically linked to the API and displayed using their file names.

• webcontent/: Contains images and .hbs content (as well as .css and .md if needed). Images can be referenced inside .hbs templates using their file names as keys. For example, if the file name is api-icon.png, it can be referenced in a template as apiImageMetadata.api-icon.

PS: The file name of OpenAPI specification (devportal-api-definition.yaml) and directory names for docs and webcontent can be overriden through the devportal-api.yaml.

A ZIP file containing the above dev portal content (e.g., devportal-d1) can be published to a standalone gateway using curl or a CLI tool.

---

Example devportal-api.yaml

apiVersion: devportal.api-platform.wso2.com/v1
kind: RestApi # (RestApi | WS | GraphQL | SOAP | WebSubApi)

metadata:
  name: pizzashack-api-v1.0  # Used as the API handle internally

spec:
  displayName: PizzaShackAPI # Stored internally as apiName
  version: 1.0.0
  description: This is a simple API for the Pizza Shack
  provider: WSO2
  referenceID: <uuid-from-cp>

  apiDefinitionPath: ./devportal-openapi.yaml
  docsPath: ./docs
  webcontentPath: ./webcontent

  tags:
    - pizza

  subscriptionPolicies:
    - gold
    - bronze

  visibility: PUBLIC
  visibleGroups: []

  businessInformation:
    businessOwner: Jane Roe
    businessOwnerEmail: marketing@pizzashack.com
    technicalOwner: John Doe
    technicalOwnerEmail: architecture@pizzashack.com

  endpoints:
    sandboxUrl: https://prod.example.com/pizzashack/v1/api/
    productionUrl: https://sand.example.com/pizzashack/v1/api/

[Piumal1999]

Based on today’s (23/03/2026) discussion, the dev portal directory structure has been updated as follows:

devportal-d1/
├── manifest.yaml # optional
├── devportal-api.yaml
├── devportal-api-definition.yaml
├── docs/
│   └── README.md
└── content/  # branding?
    ├── api-icon.png # internally we have hardcoded to use this as the API icon
    ├── api-content.hbs
    └── landingpage.css

• manifest.yaml: Acts as the entry point for the dev portal artifact and defines the directory mappings.
• devportal-api.yaml: Contains the API metadata required by the developer portal.
• devportal-api-definition.yaml: we cannot display the tryout page, operations, scopes, security schemes etc. without this
  • We can include the operations in the devportal-api.yaml, and also deduce the security schemes and scopes through policies, but then the devportal-api.yaml becomes coupled with the platform-gateway.

---

Example manifest.yaml

apiMetadataPath: ./devportal-api.yaml
apiDefinitionPath: ./devportal-api-definition.yaml
docsPath: ./docs
apiContentPath: ./content

---

Example devportal-api.yaml

apiVersion: devportal.api-platform.wso2.com/v1
kind: RestApi # (RestApi | WS | GraphQL | SOAP | WebSubApi)

metadata:
  name: pizzashack-api-v1.0  # Used as the API handle internally

spec:
  displayName: PizzaShackAPI # Stored internally as apiName
  version: 1.0.0
  description: This is a simple API for the Pizza Shack
  provider: WSO2
  referenceID: <uuid-from-cp>

  tags:
    - pizza

  subscriptionPlans:
    - gold
    - bronze

  visibility: PUBLIC
  visibleGroups: []

  businessInformation:
    businessOwner: Jane Roe
    businessOwnerEmail: marketing@pizzashack.com
    technicalOwner: John Doe
    technicalOwnerEmail: architecture@pizzashack.com

  endpoints:
    sandboxUrl: https://prod.example.com/pizzashack/v1/api/ ## This has to be a variable if the whole API artifact is imported at once
    productionUrl: https://sand.example.com/pizzashack/v1/api/

This update introduces a clear separation of concerns by using manifest.yaml as the single source of truth for the artifact structure. Similar manifest files will be used in other artifacts as well.

---

The structure of the API artifact has been updated based on the following points discussed during the meeting:

1. The api.yaml file in the root directory must be a gateway-oriented file that can be directly deplyoed to the gateway. (contain only the details required by the gateway.)

   • For a single API, all gateways must use the same api.yaml. Only parameter values may differ between gateways.
     • Values that should not be exposed directly in the YAML can be defined as variables (optionally with default values). In such cases, the corresponding values should be provided via environment variables in the gateway.
     • Values that are common across all deployments can be defined directly in the YAML instead of using variables.

2. API-related metadata that is not included in the api.yaml file should be defined in a separate api-metadata.yaml file (e.g., subscription policies available for the API).

3. Each artifact (e.g., a dev portal API artifact or a management portal API artifact) should include a manifest.yaml file to define directory mappings and configurations.

MyAPI/
├── manifest.yaml
├── api.yaml
├── api-metadata.yaml
├── api-definition.yaml
├── docs/
│   ├── readme.md
│   └── internal-doc.md
├── tests/
└── devportals/
    ├── devportal-d1/
    │   ├── devportal-api.yaml
    │   ├── devportal-api-definition.yaml
    │   ├── docs/
    │   │   └── README.md
    │   └── content/
    │       ├── api-icon.png
    │       ├── api-content.hbs
    │       └── landingpage.css
    └── devportal-2/
        └── ...

---

Example manifest.yaml

gatewayApiPath: ./api.yaml
apiMetadataPath: ./api-metadata.yaml
apiDefinitionPath: ./api-definition.yaml
docsPath: ./docs
testsPath: ./tests
thumbnail: ./api-icon.jpg

Example api-metadata.yaml

description: Lorem ipsum dolar sit amet
gatewayType: wso2/api-platform
lifecycleState: PUBLISHED
devportals:
  - portalName: devportal-d1
    artifactPath: ./devportals/dev_1 # optional. defaults to portalName
    status: PUBLISHED
deployments: 
  - gatewayName: gateway-g1
    status: DEPLOYED
    ## metadata:
    ##   - endpointUrl: "http://api.yourdomain.com

Note: moved subscriptionPlans to api.yaml since now it is available in api.yaml

[Piumal1999]

Few points to be discussed:

Source of truth for Resources/Paths of an API in the devportal

In the API platform, the source of truth for an API is the api.yaml. Currently, the API definition is not stored in the platform.

Even if an API is created using a definition, that definition is not preserved. Instead, it is converted into the api.yaml format, and much of the information from the original definition is ignored.

This is acceptable because api.yaml contains all the required details for the management portal and gateway.

However, in the devportal, we require the OpenAPI definition to display operations, enable try-out functionality, and support scopes and security scheme related processing.

• One option is to include operations in devportal-api.yaml and derive security schemes and scopes from policies. However, this approach tightly couples devportal-api.yaml with the platform gateway.

• Therefore, for the devportal, it is preferable to make the API definition mandatory and treat it as the source of truth for operations. This allows the devportal to function independently of the control plane and gateway.

Publishing to DevPortal via Management Portal

We have two possible approaches:

Option 1: Auto-generate OpenAPI definition

• Internally generate an OpenAPI definition based on operations and policies (for setting security schemes)
• Drawback: May lose elements supported in OpenAPI, such as schemas, responses, examples, etc.

Option 2: Store API definition in the platform

• Store an API definition (optionally)
• Make it editable
• Keep it in sync with api.yaml
• Allows users to modify and add additional details as needed

[Piumal1999]

Updated the structure based on the previous discussion. Latest version is available at [1].

[1] https://docs.google.com/document/d/1jvyoxzelOtIXQSyNrRjJa1Rqqi4nSQCJ8sXXsbdbj30/edit?tab=t.0#heading=h.8x4oluklm7gj