WSO2 API Manager | API Revision Feature

Here is a basic introduction to the upcoming WSO2 API Manager 4.0 API Revision Feature.

Terminology used in this post.

• “API Revision” is a snapshot of an API at a particular given time.
• “Current API” is the latest state of the API and which is also visible in the Devportal.

Note: All the API Revision feature functionalities does apply to API Products as well although i’m explaining mostly only about APIs.

Purpose

First, Let’s see what prompted us to come up with API Revisioning feature.

Previously, if we make changes to a Published API from Publisher portal and save, the changes will instantly get reflected on the API in the Devportal and to the runtime gateways. In a production environment, such a aspect would lead to severe issues if the change we apply isn’t fully tested.

Now, with the introduction of Revision Feature, API Creator/Publisher has the ability to test those changes by creating a new revision and then deploying it to a different runtime gateway environment(not to the environment exposed at Devportal) and verify the changes before making them available for the Devportal API consumers and also if something breaks should be able to restore to a previous revision which doesn’t have the affected change.

Key Functionalities

• Create/Delete/View/List API Revisions.
• Deploy/Un-deploy Revision to runtime gateway environments.
• Restore the “Current API” to a previous Revision.

Key Architectural Points

• If user perform any change related to API which affects runtime artifacts , user needs to create a new revision and then deploy the new revision.
• API Publishing and Deploying is decoupled : Previously if we Publish API, it will perform two actions; Change the lifecycle state to Published, hence API will be visible in the Devportal and it will also deploy the API artifact to gateway environments. Now, if we perform publish action it will only perform lifecycle state change action. You need to perform deployment seperately.
• Single API can have multiple revisions(Currently Only Up to 5).
• Can deploy a API Revision to already deployed environment: Here, the previously deployed revision will get un-deployed and newly selected revision will get deployed to that particular environment.
• Can create Revisions and deploy even though API is in Created State: Here, if the API is in created state, API creator is able to quickly test the API using Publisher Test Console. Previously, we didn’t support API invocation when the API is in Created State.
• Revisions are immutable: Therefore, you can guarantee that there aren’t any unknown changes causing any issue in the runtime, but once you restore back to a previous revision, the user can work on top of that revision(which will be now considered as the Current API) and perform necessary changes and then create a new revision and deploy.
• Deployed Revisions can’t be deleted: need to undeploy from all the deployed environments if needed to be deleted.

Revision Process

Lets see what we do when we create a API Revision. We store both registry artifacts as well as runtime related AM database table entries for an API at the time of Revision creation.

API registry artifacts:

• Api artefact
• Swagger.json
• API documents
• API Icon
• Wsdl artifact

Entries in following AM db tables

• AM_API_URL_MAPPING
• AM_API_RESOURCE_SCOPE_MAPPING
• AM_API_CLIENT_CERTIFICATE
• AM_GRAPHQL_COMPLEXITY

Now, let’s see what we don’t store when we create Revisions. Following will be kept common between all the API revisions and Current API.

• API lifecycle
• API Subscriptions
• API Ratings
• API Comments

API Revision Vs API Version

We can revision versioned APIs as well. (API Version is also just a new API). API Version can be used when doing a major upgrade/change to the API which might alter the current aggreement with API Consumer implementations. For Ex;

• Altering existing API resource names.
• Adding new resources.

API Revision can be used to test the changes done beforehand before making it available for API Consumers and provide a more efficient way to revert back to a stable revision in a case where the API is broken.

API Product Revision

• Same Revision capabilities will apply for API Products as well.
• When creating API Products, In the API Products resource selection wizard, Current API resources will be used. Here, we aren’t binding a revision with a product.

Now, we have a understanding of what to expect from the feature. Let’s try out few sample scenarios.

Sample Demo 1 — PizzaShack Sample API

1. Download/Build API Manager 4.0 pack and start the API Manager using following command.

sh wso2server.sh

2. Go to the Publisher Portal and login using admin/admin.

3. Deploy the sample Pizzashack API.

Deploying Sample API

Here, the Deploy Sample API Performs following 4 functions,

• Create API
• Create Revision
• Deploy Revision
• Publish API

So if you go inside the API you should be able to see there are already revisions created and deployed. This will not be the case if you create an API from the scratch.

Sample API Overview

So as you can see, now you are in the Current API, from that only we can create and deploy revisions.

4. Navigate to Deployments tab.(Optional)

Deployments Tab

As you can see we already have a revision create and deployed in the default gateway.

Therefore, in the sample Pizzashack API you don’t need to create a revision and deploy. But if you make a change to the Sample API, you must create a new revision and deploy to changes to take effect.

5. Invoke the Sample API by subscribing to an Application from the devportal.

API Invocation

Sample Demo 2 — API from an Open API Definition(Petstore)

1. Select Import Open API option

Create Open API Option

2. Provide Following Details and create the API

Provide OpenAPI

Create API

OpenAPI url: http://petstore.swagger.io/v2/swagger.json

Endpoint: http://petstore.swagger.io/v2/

3. View API Overview(Optional)

API Overview

As you can see, when we create an API from scratch we don’t by default create revisions and deploy.

4. Select necessary Business Plans(Ex: Unlimited)

5. Go to Deployments tab and click Deploy New Revision button.

Deploy New Revision

Provide necessary description(optional) and then select relevant gateway environment to be deployed and also select Vhost as well. Then click Deploy button.

Deployments View

As you can see, Revision 1 has been created and also deployed successfully to the selected gateway.

6. Go to the Overview tab and click Publish button.

Publish API

7. Go to the Devportal and Subscribe and Invoke the API.(Need to generate a token with relevant scopes)

Sample Demo 3 — Revision Functions

Prerequisites above demos

1. Make a change to the Petstore API

Adding a new request message mediation.

Common Policies

2. Save the API

3. Invoke the API and check the wso2carbon.logs

Here you won’t find any logs related to message mediation since we haven’t created a new revision and deployed that revision to gateway. API artifacts which is deployed current doesn’t have message mediation change we did although we did click save button. This change is still applied in the Current API.

4. Create a new Revision and Deploy.

Create Revision 2 and Deploy

Deployments

As you can see, new Revision 2 is now deployed in the gateway environment.

3. Invoke the API and check the wso2carbon.logs

Now, you will be able to see following kind of logs.

[2021–03–15 18:13:49,346] INFO — LogMediator {api:SwaggerPetstore:v1.0.5} To: /v2/1.0.5/pet/findByStatus?status=available, MessageID: urn:uuid:d3d18bdb-9a05–4263-b2a4–16566e2f249c, correlation_id: 78168727–6d44–4e7d-9bf0–3aa73b2c6ca1, Direction: request, IN_MESSAGE = IN_MESSAGE, Envelope: <?xml version=’1.0' encoding=’utf-8'?><soapenv:Envelope xmlns:soapenv=”http://www.w3.org/2003/05/soap-envelope"><soapenv:Body/></soapenv:Envelope>

Therefore, as you can see, new changes has been gone to the gateway only after we create a new revision and deploy.

4. Restore the API to previous Revision

Click Restore button in the Revision 1.

Navigate to Runtime Section to verify that the previous change we did isn’t present since we have restored the API to a previous revision.

None in the Message Mediation

5. Invoke the API and Verify the wso2carbon.logs

Here, although we have restored the API, it doesn't affect the deployed revision. Since we have Revision 2 Deployed(which has mediation log change), in the wso2 carbon.log we could observed same mediation log printed.

6. Undeploy and Deploy a Revision

If you need to change the deployed revision back to Revision 1, which doesn't has mediation log change.

Click Undeploy

Select Revision and Vhost and Deploy

Now, the Revision 1 is successfully deployed.

7. Invoke the API and Verify the wso2carbon.logs

Now, you won’t see the logs printed from mediation logs since we have deployed a old revision which doesn’t have medation log change.

8. View Revisions

Select the Revision from Drop Down

DropDown

If you navigate to Revision 1, you will see empty mediation policy.

Revision 1 Runtime Tab

If you navigate to Revision 2, you will see log mediation policy engaged.

Revision 2 Runtime Tab

9. Delete Revisions

You can’t delete deployed Revisions(Greyed out delete button), Revisions which are unused can be deleted.

After deleting unused Revision 2

Only Revision 1 is now present.

These UI Images and some Functionalities are expected to be undergo changes. This doc is currently in accordance with carbon-apimgt:9.0.50(After Alpha). After, the release will alter the post accordingly.

Hopefully, you gained some understanding of the feature.

See you all in the next post !!