[Proposal] API Platform CLI: User Flow and API Project Model

[ShakyaPr]

Summary

This document proposes a unified CLI user flow for API Platform that enables users to manage API projects and interact with platform components through a consistent command structure.

The CLI is designed to treat the Management Portal, Gateway, and Developer Portal as independent components. Users can configure and operate each component separately, while the CLI directly communicates with each system when executing commands such as build, push, and publish.

It also introduces a standard API project structure and environment-based configuration, allowing users to manage APIs from initialization to deployment using a single, predictable workflow.

Initial Discussion for CTL design can be found from here: #356

Goals

• Finalize the API Platform CLI user flow.
• Provide a standard API project structure to manage APIs from initialization to deploy to different components.
• Support independent operations for Management Portal, Gateway, and Developer Portal.
• Support both interactive and non-interactive CLI usage.
• Make the CLI easy to understand by looking at the command pattern

Core Concepts

CLI Environment

• A CLI environment is a named configuration context representing a workspace of connected components. It's a logical boundary used to group related components such as Management Portals, Gateways & Developer Portals withing the API platform.

• Each environment can contain:

  • One Management Portal
  • Multiple Gateways
  • Multiple Devportals

• When the CLI is first installed, default environment will be always exists. So, users do not need to create an environment to use the CLI.

• Users can add Management Portals, Gateways & Devportals to the environment.

• If multiple environments exist, user can switch the active environment. All the subsequent commands will be executed against the active environment if user doesn't specifically select the environment.

Command Categories:

• Global Commands : Executed from any location (Ex: init, add env, list, add)
• Project Commands : Require a project context to execute (Ex: build, deploy, publish), use the selected environment context if no environment specifically added
• Component Commands: Required org context for Devportal & Management Portal, the commands comes in this category maps to the functionalities define through REST API of the Service.

Command Execution logic

• For project-level and component-level commands, the CLI requires enough context to identify:
  • The target environment
  • The selected component
  • The organization

1. Explicit Arguments - Users can pass all required parameters directly in the command.
   Ex:

ap devportal apply --name <devportal-name> --env <env> --org <org> --file <path-to-api-project-zip>

This approach is useful for scripting and automation, where each command must be self-contained.

2. Context-Based Execution - Instead of passing all parameters every time, users can set contexts once and run simpler commands.

Ex:

ap env use --name prod      # select prod environment
ap devportal use --name devportal            # select a devportal component, here since no environment is defined it checks for the currently setted environment as its env & checks for a devportal with given name
ap devportal use --org ABC            # set the org to `ABC` for subsequent commands to be executed for currently selected devportal
ap devportal apply --file foo-1.0.0.zip        # Here since no `--env`, `--org`, `--name` args have been used, it checks for the currently setted contexts & tries to execute command

Context Resolution Behavior

When a command is executed without explicit arguments, the CLI resolves values using the current context:

• If --env is not provided, the CLI uses the active environment.
• If --name is not provided, the CLI uses the selected component within the active environment.
• If --org is not provided, the CLI uses the currently set organization.
• If --file is not provided, the CLI attempts to resolve the API project from the current directory.

If any required context is missing, the CLI should prompt the user or return an error.

API Project

An API project is similar to a git repository - it's a directory-based workspace where you can run commands from anywhere within the project structure.

Project identification

For a directory to be recognized as an API project, it must contain:

• A .api-platform/ directory
• A config.yaml file within .api-platform/

Command Resolution

When the user executes a command, the tool initiates an upward traversal:

• The tool checks the current directory for .api-platform/config.yaml.
• If not found, it moves to the parent directory and repeats the search.
• Once the configuration is found, the tool uses those paths to resolve project files.
• This allows the user to run project-specific commands from any subdirectory.
• Also, users can use --path flag to point the project folder to provide support to run the commands from anywhere

Component Independance

The CLI treats the Management Portal, Gateway, and Developer Portal as independent systems under an environment. The tool does not interact with one component through another.

• Direct Interaction: To deploy an API to a gateway, the CLI communicates directly with the Gateway’s management API. It does not request the Management Portal to handle the deployment.
• Orchestration via CLI: When a user performs multiple actions at once (e.g., adding an API to the Management Portal and deploying to the Gateway), the CLI handles this by executing separate requests to each component.

High-level CLI User Flow

flowchart TD
    A[Install API Platform CLI] --> B[Default environment is available]

    B --> C[Add platform components]
    C --> C1[Add Management Portal]
    C --> C2[Add Gateway]
    C --> C3[Add Developer Portal]

    C1 --> D[Add/Set active environment]
    C2 --> D
    C3 --> D

    D --> E[Initialize API project]
    E --> F[Create API project structure]

    F --> G[Design or edit API definition]
    G --> H[Build gateway artifact]
    G --> I[Build developer portal artifact]

    H --> J[Push directly to Gateway]
    I --> K[Push directly to Developer Portal]
    G --> L[Push directly to Management Portal]

    J --> M[API deployed in Gateway]
    K --> N[API published in Developer Portal]
    L --> O[API registered in Management Portal]

Loading

CLI User Flow

Step 1: Setting up the Environment

Before performing project operations, the user must configure the required components: management portal, gateways, devportals and authenticate.

ap management-portal add --name <name> --organization <org> --server <server-url>
ap devportal add --name <name> --server <server-url>
ap gateway add --name <name> --server <server-url>

Users can use either interactive or non interactive mode to add platform component with desired auth type

Upon successful addition & authentication, users can use global level commands to manage components & get the component status.

Ex:

command	purpose	Ex:
list	list the available components set of given component type	ap devportal list
remove	remove a specific component	ap devportal remove --display-name <name>
use	select a specific component	ap devportal use --name <name>
current	To see the selected component	ap devportal current

Step 2: Initialize API Project

There are two ways to create API Project

• Option A: Using VSCode plugin

1. Open VSCode plugin
2. Select: Create New API
3. Choose creation method: AI-Assisted or Manual
4. Provide API details (name, version, type, context) and create

• Option B: Using CLI

ap init FooAPI --type rest --version 1.0.0 --context /foo
# OR
ap init # interactive mode

**Output after Step 2: **

Folder Structure

FooAPI/
├── .api-platform/
│   └── config.yaml
├── gateway.yaml		# for gateway deployment 
├── api.yaml		# additional metadata for management portal
├── definition.yaml	# openapi definition
├── docs/
│   └── (empty) 	# can include a default README file
└── tests/
    └── (empty)

File: .api-platform/config.yaml

version: 1.0.0

# Default file paths (can be customized)
filePaths:
  deploymentArtifact: ./gateway.yaml
  apiMetadata: ./api.yaml
  apiDefinition: ./definition.yaml
  docs: ./docs
  tests: ./tests

# Governance rulesets for design-time validation
governanceRulesets:
  - name: OWASP Top 10
    sourceFolder: https://github.com/wso2/api-platform/tree/main/api-designer/spectral-rulesets
    fileName: owasp_top_10.yaml
    rulesetContentPath: rulesetContent
  - name: WSO2 API Standards
    sourceFolder: https://github.com/wso2/api-platform/tree/main/api-designer/spectral-rulesets
    fileName: wso2_standards.yaml
    rulesetContentPath: rulesetContent

# Auto-sync configuration for vscode plugin
autoSync:
  gatewayArtifactFromDefinition: true  # Auto-generate api.yaml when api-definition.yaml changes

File: api.yaml

apiVersion: management.api-platform.wso2.com/v1
kind: Api
metadata:
  name: foo-1.0.0                      # Generated from context + version combination of init command
spec:
  description: ""
  gatewayType: wso2/api-platform

Step 3: Design API Using Designer Tool

User edits the definition.yaml file using the Designer tool to define paths, operations, schemas, etc.

Generate the gateway.yaml

• **Option A: ** Auto-sync (if enabled in config.yaml)

  • Changes are automatically detected
  • gateway.yaml is regenerated automatically

• **Option B: ** Manual Generation

  • Click "Generate Gateway Config" button in Designer tool
  • Or run CLI tool : ap gateway build or ap gateway build --path <API-Project-path>

Output After Step 3:

File: gateway.yaml

apiVersion: gateway.api-platform.wso2.com/v1
kind: RestApi
metadata:
  name: foo-api-v1.0
spec:
  displayName: Petstore API
  version: v1.0
  context: /petstore
  upstream:
    main:
      url: http://sample-backend.org:9080 		# or as ${BACKEND_URL}
  operations:
    - path: /foo
      method: GET
    - path: /foo
      method: POST
    - path: /foo/{fooId}
      method: GET
    - path: /foo/{fooId}
      method: DELETE

Step 4: Build Devportal Artifact

Command:

ap devportal build 
# Or
ap devportal build --file <API-Project-Path-zip>

What Happens after the command

This checks for any existing developer portal configurations in the project. (using config.yaml)

• Scenario 1: Devportal config doesn't exist:

If no portal configuration exists in config.yaml, the tool initializes a /devportal directory and updates config.yaml.

Output:

✓ Default devportal artifact initialized and built successfully
Next Steps:
  Run 'ap devportal publish' to publish to devportal.

• Scenario 2: Devportal config exists
  • Uses existing devportal/ directory (or the files based on the config)
  • Validates configuration
  • Generates a devportal artifact (build/devportal-name.zip)
  • The artifact will always contains the files in the standard directory structure and the file names regardless of the custom filepath configurations.

Output after Step 5:

Directory Structure:

FooAPI/
├── .api-platform/
│   └── config.yaml
├── build/
│   └── devportal.zip # ✓ NEW (Compressed artifact for upload)
├── gateway.yaml
├── api.yaml
├── definition.yaml
├── docs/
├── tests/
└── devportal/         # ✓ NEW
    ├── devportal.yaml      	   # ✓ NEW (devportal api-metadata) 
    ├── definition.yaml        # ✓ NEW (copied from root)
    ├── docs/                  # ✓ NEW (copied from root)
    └── content/               # ✓ NEW

File: .api-platform/config.yaml

...
# Dev portal configurations  		# ✓ NEW SECTION
devportals:                  		# ✓ NEW
  - name: default   			# ✓ NEW
    portalRoot: ./devportal  		# ✓ NEW
    filePaths:				# paths relative to portal root
      apiMetadata: ./devportal.yaml
      apiDefinition: ./../definition.yaml
      docs: ./docs
      content: ./content

File: devportal/devportal.yaml

apiVersion: devportal.api-platform.wso2.com/v1
kind: RestApi

metadata:
  name: foo-1.0.0               # Copied from api.yaml

spec:
  displayName: foo
  version: 1.0.0
  description: ""
  provider: WSO2
  referenceID: 550e8400-e29b-41d4-a716-446655440000.       # By default this will be empty

  tags:
    - default

  subscriptionPlans:		# All subscriptionPlans in gateway.yaml if no empty array []
    - gold
    - silver
    - bronze

  visibility: PUBLIC
  visibleGroups: []

  businessInformation:
    businessOwner: ""
    businessOwnerEmail: ""
    technicalOwner: ""
    technicalOwnerEmail: ""

  endpoints:
    sandboxUrl: ""
    productionUrl: ""

Step 5: Push Artifacts to Platform Components

Import API to Management Portal

# Import API to management portal (to the selected project)
ap management-portal apply              # if the org, project has already been set
# Or
ap management-portal apply --org <org> --project <project>

When execute this:

• Uploads gateway.yaml, api.yaml, definition.yaml and docs/ to management portal.
• Creates an API entry in management portal
• Returns API ID & Management portal URL

*Output:
shell output:

✓ API added to management portal successfully
API ID: 550e8400-e29b-41d4-a716-446655440000
Management Portal URL: https://example.com/organizations/:orgHandle/projects/:projectName/apis/:apiHandle

FIle: api.yaml will be updated with API ID

description: ""
gatewayType: wso2/api-platform
apiId: 550e8400-e29b-41d4-a716-446655440000  # Newly updated
...

Push API to Devportal

ap devportal apply --org <org> -f <API-Project-path>   # if no org context has been set
# Or
ap devportal apply                        # if org context has been set & command executes inside a project directory

Output:

✓ Dev portal artifact published successfully
Dev Portal: default
API URL: https://devportal.example.com/apis/550e8400-e29b-41d4-a716-446655440000

Deploy API to Gateway

# Deploy to a specific gateway
ap gateway apply -f gateway.yaml

What happens:

• CLI reads gateway.yaml from the path specified in .api-platform/config.yaml
• Validates the gateway yaml file
• Deploys to the specified gateway
• Returns the deployed URL

Output:

✓ API deployed successfully
Gateway Endpoint: https://gateway.example.com/foo/v1.0

[ShakyaPr]

Discussion 29/04/2026

• Instead of using environment wording as it could introduce confusion to the customers, decided to continue with word platform.