[Discussion Summary] Refactoring Deployment API Endpoints for Better RESTful Design

[dushaniw]

Problem

The current deployment endpoints are inconsistent and don't follow clear RESTful patterns:

POST /apis/{apiId}/deploy
POST /apis/{apiId}/deployments/{deploymentId}/undeploy  
POST /apis/{apiId}/rollback-deployment?deploymentId=

We had a discussion on the $subject and decided on a better design. Following is the summary.
Participants : @malinthaprasan @VirajSalaka @renuka-fernando @dushaniw

Issues:

• Inconsistent resource hierarchy (some at API level, some at deployment level)
• "rollback" terminology is negative (implies failure)
• Gateway relationship not clearly expressed in URLs
• Potential for operational errors (e.g., targeting wrong gateway)

Key Context

• A deployment is bound to a specific gateway - each deployment artifact is associated with exactly one gateway
• These operations change the deployment state of an API on a gateway - not just individual deployment resources
• When you deploy/undeploy/restore, you're managing which deployment version is active on a specific gateway

Alternatives Considered

Alternative 1: Gateway-First Hierarchy

POST /gateways/{gatewayId}/apis/{apiId}/deployments
POST /gateways/{gatewayId}/apis/{apiId}/deployments/undeploy
POST /gateways/{gatewayId}/apis/{apiId}/deployments/restore

Rejected because:

• User mental model is "deploy my API" not "manage this gateway"
• More complex URLs with deeper nesting
• Gateway is infrastructure. API is the primary entity being managed
• Less common query pattern (more often ask "what deployments for this API?" vs "what's on this gateway?")

Alternative 2: Deployment-Level Actions

POST /apis/{apiId}/deployments
POST /apis/{apiId}/deployments/{deploymentId}/undeploy
POST /apis/{apiId}/deployments/{deploymentId}/restore

Rejected because:

• Misleading semantics: These operations don't act on individual deployments
• They change the entire deployment state of the API on a gateway
• deploymentId is more of a version selector than a target resource
• Doesn't clearly show the gateway relationship

Alternative 3: API-Level Actions with Query Params

• POST /apis/{apiId}/deploy
• POST /apis/{apiId}/undeploy?deploymentId={id}&gatewayId={id}
• POST /apis/{apiId}/restore?deploymentId={id}&gatewayId={id}

Rejected because:

Inconsistent: deploy at API level, others require params
Doesn't clearly express that these are deployment collection operations

Final Solution: Collection-Level Actions

POST /apis/{apiId}/deployments
  Body: { "name": "...", "gatewayId": "...", ... }
  → Creates AND deploys to gateway

POST /apis/{apiId}/deployments/undeploy?deploymentId={id}&gatewayId={id}
  → Undeploys API from that gateway

POST /apis/{apiId}/deployments/restore?deploymentId={id}&gatewayId={id}
  → Restores API on that gateway to this deployment version

Why This Solution?

• Correct semantics: Operations on /deployments collection reflect that you're managing the deployment state, not individual resources

• Explicit safety: Requiring gatewayId even though it's in the deployment prevents operational mistakes
  - Example: Prevents accidentally undeploying from prod when targeting dev
  - Backend validates deployment.gatewayId == query.gatewayId

• Consistency: All actions follow the same pattern with explicit parameters

• Clear intent: Actions are "collection-level" operations on the API's deployments

• Better terminology: "restore" is neutral vs "rollback" which implies failure

• Gateway relationship: Gateway ID is explicit in all operations

Terminology Decision

• restore over "rollback": Neutral, doesn't imply current deployment is problematic