Resource Synchronization in Virtual REST APIs

REST APIs are bound to change and evolve over time as they move through development, test and production. Modifications or enhancements such as, adding additional resources, HTTP methods or parameters, modifying the existing capabilities of resources, methods or parameters are performed on a particular REST API. In the case of a REST API that is virtualized to create a new Virtual REST API, keep in mind that the Virtual REST API which is newly created is an identical copy of the existing Native REST API and not just a reference REST API. This means that after a Virtual REST API is created, any subsequent changes in the Native REST API are not automatically propagated to the Virtual REST API. This means that if you add Resource B to the Native REST API, the newly added Resource B is not added to the existing Virtual REST API.

CentraSite provides the ability to deal with evolution of REST APIs. Depending on the nature of change in the Native REST API and your versioning strategy, CentraSite offers different mechanisms:

Versioning the REST APIs: The CentraSite Business User Interface allows versioning of Native REST APIs and Virtual REST APIs. You can make the following kinds of versions on the REST APIs:

Create a new version of the existing Native REST API, make the necessary changes to the new version, and then create a Virtual REST API from the new version. We recommend that you use this kind of versioning when there is a requirement for considerable change in the Native REST API.

Resynchronizing the REST APIs: The CentraSite Business User Interface allows resynchronization of the Virtual REST APIs. This means that you copy the resource definition of the Native REST API (which includes HTTP methods, parameters, or sample requests and responses) to the Virtual REST API without affecting other configurations such as, the run-time policy actions and the consumption settings.

CentraSite Business UI offers the possibility of synchronizing the REST resource metadata for a Virtual REST API.

Note that there is no automatic synchronization of resource metadata between the REST API and the Virtual REST API. If you want to have the resource metadata in the Virtual REST API to be the same as the resource metadata in the REST API, you must manually reconfigure the resource metadata in the Virtual REST API to synchronize with the resources in the REST API.

The user must have API Runtime Provider role to manage synchronization for the specified Virtual REST API.

When planning for the resource synchronization in Virtual REST API, as a best practice, take the following points into consideration:

If you want to simply reconfigure the run-time policy action configurations for a particular Virtual REST API, we recommend that you use the Virtualize action in the details page of that Virtual REST API.

If you want to reconfigure the alias field labeled Endpoint prefix for invocation alias or synchronize resources for a particular Virtual REST API, we then recommend that you use the Virtualize action in the details page of that Native REST API.

Be aware that only the additions and deletions at the resource-level are recognized by the Virtualize action during reconfiguration of a Virtual REST API. Any changes that are made at the API-level and method-level are not recognized.

When you allow synchronization to happen on the Virtual REST API, the updated metadata of the Native REST API will completely overwrite the existing metadata of the Virtual REST API.

For example, if you have a Native REST API with two resources - Resource A and Resource B. Consider these two resources have the following methods:

Assume you virtualize the Native REST API to create a Virtual REST API.

The Virtual REST API will include the two resources - Resource A and Resource B with the above specified methods.

Consider you update the details page of the Native REST API to include an additional metadata “DELETE Method” to the existing Resource B. The Native REST API will now have the two resources with the following methods:

Consider you update the details page of the Virtual REST API to include an additional metadata “DELETE Method” to the Resource B. The Virtual REST API will now have the two resources with the following methods:

When you reconfigure the Virtual REST API from the details page of the Native REST API, in the Recreate resources section, CentraSite displays both the resources - Resource A and Resource B (with a comment "already exists") with pre-selected check boxes by default.

Note that the Resource B has a different set of method specification for the Native and Virtual REST APIs. However, on reconfiguring the Virtual REST API, this difference of the method specification is not recognized in the user interface.

Now when you choose to reconfigure the Virtual REST API with the default selection, upon synchronization, the existing metadata of the Virtual REST API will be completely overwritten by the updated metadata of the Native REST API. As a result, the Resource B of the Virtual REST API will now contain the inherited POST Method; but the user-defined DELETE Method will no longer exist.

Important:

As a best practice, we recommend that you maintain the Native REST API as the single point of truth and synchronize all your changes with the Virtual REST API using the synchronization process.

Resource A	Resource B
GET Method	GET Method
POST Method	PUT Method