Add API undeployment through Gateway Controller REST API

Current Limitation

The gateway-controller currently only supports permanent deletion of APIs via the DELETE /apis/{id} endpoint, which has the following behavior:

What DELETE does:

• Removes API configuration from database
• Deletes all API keys
• Removes all policies
• Stops router traffic
• Cannot be reversed - all data is permanently lost

WebSocket vs REST API Gap:

• ✅ Platform-API → APIUndeployedEvent (WebSocket) → Gateway sets status="undeployed" (preserves data)
• ❌ Gateway REST API → Only DELETE available → Permanent removal

Missing Use Cases:

• Temporary maintenance windows without losing credentials
• Staged rollouts (undeploy v1, deploy v2, rollback if v2 fails)
• Testing deployment workflows locally
• Debugging production issues while preserving configuration
• Manual intervention matching platform-triggered undeployment

Suggested Improvement

This is being discussed in https://github.com/wso2/api-platform/discussions/714#discussioncomment-15555381

Option 1: Separate REST Endpoint

Add dedicated POST /apis/{id}/undeploy endpoint.

Usage:

# Undeploy
POST /apis/{id}/undeploy

# Redeploy (use existing PUT)
PUT /apis/{id} with API YAML

Pros:

• Clear, explicit intent
• Simple single command to suspend
• No YAML file needed for undeploy

Cons:

• Asymmetry: POST to undeploy, PUT to redeploy
• Duplicates functionality (PUT already redeploys)
• Not declarative (conflicts with GitOps/K8s patterns)
• Additional endpoint to maintain

Option 2: Declarative State in YAML (Recommended)

Add deploymentState field to API YAML spec, handle via existing [PUT /apis/{id}].

Enhanced YAML:

spec:
  deploymentState: undeployed  # or: deployed (default)
  displayName: Weather-API
  version: v1.0
  # ... rest of config

Usage:

# Both undeploy and redeploy use same endpoint
PUT /apis/{id} with YAML (deploymentState: undeployed)
PUT /apis/{id} with YAML (deploymentState: deployed)

Pros:

• Declarative state matches GitOps/K8s patterns
• Single endpoint for all changes
• Idempotent operations
• K8s Operator ready (CRD maps directly to spec)

Cons:

• Requires YAML file (can't undeploy with single command)
• More verbose for simple state changes

Note: Can add CLI helper ([ap gateway api set-state] for convenience while keeping REST API clean.