[Proposal] API Artifact Directory Structure for API Platform

[Piumal1999]

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. This can be in other formats such as .graphql

• 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

spec:
  apiHandle: PizzaShackAPI-v1
  displayName: PizzaShackAPI
  version: 1.0.0
  description: This is a simple API for the Pizza Shack
  provider: WSO2

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

  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://localhost:9443/am/sample/pizzashack/v1/api/
    productionUrl: https://localhost:9443/am/sample/pizzashack/v1/api/