Revision Management in API-Platform

[VirajSalaka]

Revision: The deployable/deployed API artifact in a gateway. By looking at the revision, we should be able to identify exactly what is deployed in gateway. Comparing revisions, we could identify the changes shipped for different gateways as well as see the difference between the changes pushed for the same gateway.

It is the same revision concept as in wso2 api manger.

How do we plan to achieve the same feature in api-platform?

[nuwand]

Unlike API Manager, the API Platform is supposed to be tightly integrated with Git. Although not mandatory, maintaining API specs, docs, deployable artifacts, etc in Git is the recommended way of using the API Platform. For someone who wants revisions, what if we just say rely on Git instead of having to build anything specifically in the product?

[slahirucd7]

@VirajSalaka @nuwand
Just to remind, we need to consider revisions considering the Hybirid GW integration to control-plane as well. Currently in the control plane we are handling revisions. If revisions are going to be handled only considering the Git, then control plane will only have consider and handle it as well. Can we provide option to select

• Git based revisions
• API-Platform Managed revisions during the API creation time ?
  Allowing only to have Git based revisions is problematic when considering the Hybrid GW integration scenarios.

[VirajSalaka]

It means that if you are not depending on Git, then revisioning is not supported.

I have following questions.

1. Organizations may have more than one gateways. And then we need a way to keep track of which changes are deployed in which gateway. And without revision feature, we cannot achieve this if the user does not use Git.

There could be users who use two gateways to mimic their Dev And Prod Environment.

2. How do we handle the changes the API developers do via Portals? Let's say the developer added a policy. Does API-Platform somehow has access to the github repo with write action?
3. If we bring the workflow approval, governance validation we should have some defined artifact which could be approved and validated. So do we ignore this for developers who create API with openapi straightaway.
4. With revision feature, we can track clearly whether the changes you made become available in gateway. Let's say platform-api has some api changes, but deploy action is not triggered. Now we probably won't know what is deployed in gateway. With revision feature, we can exactly say which is deployed in Gateway.

For Bijira I think we need the revision feature because we cannot cut features if the user does not use git. If API-Platform does not have this we have to solve separately for Bijira.

[dushaniw]

Irrespective of the design choice to provide option for change management through Git revisions or platform managed revisions, we anyway need an immutable artifact by bundling the API with its specific gateway configuration into a single, traceable unit.

"Flagged Revisions" Model

If we are to bring an explicit re-visioning model in platform which is separate from git change management, it should be a hybrid approach to combine stable, explicit revisions with the flexibility needed for environment-specific deployments.

The Base Model: Simple Revision Management

The foundation is a simple system where a user creates a major, immutable Core Revision (e.g., Revision 5) when they have a stable, testable version of their API's logic.

The Challenge: Environment-Specific Configurations

The key challenge is how to apply different configurations (e.g., for Staging vs. Production) to the same core revision without creating a new, confusing major revision just to change a configuration value.

The Proposed Solution: "Flagged" Revisions

This model introduces the concept of a Flagged Revision: a lightweight, system-generated child of a core revision. It would be created automatically upon deployment and would immutably bundle the parent revision's logic with the specific configuration for that single deployment.

For example, when a user deploys Revision 5 to Staging, the system would create a flagged revision, 5.1-staging. Deploying the same Revision 5 to Production would create another, 5.2-production.

The theoretical benefits of this were:

• It maintains a clear parent-child relationship, which supports a safe promotion workflow.
• The UI could be designed to show only major revisions by default, keeping the main history list clean.
• Each flagged revision would be an immutable artifact, providing an audit trail.

---

2. Drawbacks

Despite the benefits, this approach has several critical concerns:

1. History Pollution: Even if hidden in the UI, the backend would accumulate a large number of minor, flagged revisions. A single logical API change could result in dozens of these artifacts, making the underlying history difficult to manage and prone to clutter.

2. Configuration Complexity: It complicates the management of gateway-specific settings. Since each flagged revision is tied to a specific deployment, the configuration becomes implicitly part of the revision itself. This blurs the line between the API's logic and its deployment configuration.

3. Data and Code Complexity: This model requires storing a complete snapshot of the API definition with every single deployment-specific revision. This leads to significant data duplication and requires a complex relational data structure. To be specific, you would likely need to add a revision_id foreign key column to many different tables in the data layer—tables for policies, endpoint configurations etc. Every individual part of an API's configuration would need to be linked back to a specific revision. This creates a web of relational data that is difficult to query and maintain, as assembling a full picture of a single deployment would require complex database joins.

[dushaniw]

To overcome the above drawbacks of an explicit revision model, following is a proposal for a much simpler approach we could implement for the initial phase. As we go on and define the exact design choices for change management for APIs, we could improve this later.

Proposal: API Deployment Artifacts

1. Problem Statement

The API Platform needs to provide a flexible and robust mechanism for deploying APIs to various gateways. The solution must support traceability and promotion workflows (e.g., Staging to Production) without enforcing a single, rigid environment model. Instead, it should provide powerful, unopinionated building blocks that customers can use to construct their own CI/CD pipelines and release processes. The core of this is the ability to create immutable deployment artifacts that can be reliably deployed and promoted across different gateways, each with its own specific configuration.

2. Proposed Design: A Deployment-Centric Model

The proposed design is centered around a new core concept: the Deployment.

A Deployment is an immutable, self-contained artifact that represents a specific snapshot of an API, bundled with the gateway-specific configurations it was deployed with. Each time an API is deployed to a gateway, a new Deployment artifact is created.

Key Principles:

• Each Deployment artifact is a fully self-contained copy of the API definition and its configuration. It has no dependency on its base, meaning a base deployment can be deleted without affecting any children created from it.
• This model does not prescribe a strict environment hierarchy. A deployment to a "staging" gateway and a "production" gateway are simply two independent deployment events that produce two independent artifacts.

3. User Workflows

This model supports two primary workflows:

Workflow A: Deploying the Latest API Changes

This is the flow for deploying new work.

1. A developer makes changes to the API definition (the "Current API").
2. They initiate a deployment, targeting a gateway.
3. They select "Current API" as the base for the deployment.
4. They provide the gateway-specific configuration (e.g., rate limits, CORS settings) as key-value pairs for this specific deployment.
5. The system creates a new Deployment Artifact, "burning in" the API definition and the provided configuration. This new artifact is then deployed to the target gateway.

Workflow B: Promoting or Re-deploying an Existing Deployment

This is the flow for promoting a deployment to a new gateway (e.g., from Staging to Production) or re-deploying an existing artifact.

1. A developer chooses an existing, stable Deployment from the deployment history (e.g., deployment-v5-staging, which was successfully tested).
2. They initiate a deployment from this artifact.
3. The system uses the selected artifact (deployment-v5-staging) as the base. The API configuration is copied from this base.
4. The developer targets a new gateway (e.g., "Production Gateway").
5. They provide a new set of configuration values suitable for the production environment.
6. The system creates a new Deployment artifact (e.g., deployment-v6-prod) containing the same base API logic but with the new production configuration burned in. This new artifact is then deployed.

4. Deployment Lifecycle

This model introduces a stateful lifecycle for each deployment artifact, allowing for a full deployment history to be maintained for each gateway.

1. Deploy: When a deploy-api call is made, a new Deployment artifact is created with a status of DEPLOYED. If another deployment was already active on the target gateway, that older deployment's status is automatically changed to UNDEPLOYED.
2. Undeploy: A user can undeploy an active deployment. This action changes the deployment's status to UNDEPLOYED but preserves the artifact in the system's history. This allows the deployment to be re-deployed later.
3. Delete: A deployment that has a status of UNDEPLOYED can be permanently deleted. This action is irreversible and is intended to help manage storage or conform to potential deployment count limits for a gateway.

5. API and Data Model

The following API endpoints and data structures will be implemented to support this design.

API Endpoints:

Platform API

• POST /apis/{apiId}/deploy-api/

  • Creates a new deployment artifact and deploys it to a gateway. If another deployment is active on that gateway, it is automatically marked as UNDEPLOYED.
  • Parameters:
    • base (string): The source for the API definition. Can be "current" (to use the latest working copy) or a deploymentId of an existing deployment to use as a template.
    • gatewayId (string): The ID of the target gateway.
    • metadata (map): A flexible key-value map for all gateway-specific settings.
  • Response:
    • deploymentId (string): The ID of the newly created deployment.

• POST /apis/{apiId}/deployments/{deploymentId}/redeploy

  • A convenience endpoint to re-deploy an existing, inactive deployment artifact to its original gateway. This changes its status to DEPLOYED and undeploys the currently active deployment on that gateway.

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

  • Undeploys an active deployment by changing its status to UNDEPLOYED. The historical artifact is preserved. Fails if the deployment is already inactive.

• DELETE /apis/{apiId}/deployments/{deploymentId}

  • Permanently deletes an undeployed deployment artifact. Fails if the deployment is currently active.

• GET /apis/{apiId}/deployments/

  • Returns a list of deployment metadata objects for the specified API. Can be filtered by gatewayId and status.

Internal API

• GET /apis/{apiId}/deployments/

  • Returns a list of deployment metadata objects for the specified API. Can be filtered by gatewayId and status.

• GET /apis/{apiId}/deployments/{deploymentId}/content

  • Returns the raw, immutable deployment artifact (blob) for a specific deployment.

Data Model:

• Deployment:
  • deploymentId (string): The unique identifier for this artifact.
  • gatewayId (string): The ID of the gateway this artifact is associated with.
  • status (string): The current state of the deployment (e.g., DEPLOYED, UNDEPLOYED).
  • creationTimestamp (string): Timestamp of when the deployment was created.
  • metadata (map): A copy of the key-value settings provided at creation time.

6. Open Questions and Future Considerations (Grey Areas)

This design provides a flexible foundation. However, several areas, particularly around Git integration, require further exploration.

1. Duplication of Workflow: If an organization uses Git for version control, revisions are already managed via commits and tags. How do we reconcile the platform's deployment history with the Git history? Should the platform simply reflect the Git history, or does it provide a separate, complementary workflow?
2. Separation of Concerns in Git: Should the API contract and environment configurations reside in separate Git repositories? If so, a deployment might be defined by two separate commit IDs. The flexible metadata field in the deploy-api call is the intended place to pass this information (e.g., api_commit_hash: "...", config_commit_hash: "..."). How the platform UI would accommodate this workflow requires further design.
3. Configuration Placeholders: Currently, configs are supplied as literal key-value pairs. Should we introduce a common placeholder syntax (e.g., ${rate_limit}) within the API configuration that gets substituted at deployment time from the environment configuration?