Resource Synchronization in Virtual REST Services

REST Services 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 the particular REST Service. In the case of a REST Service that is virtualized to create a new Virtual REST Service, keep in mind that the newly created Virtual REST Service is an identical copy of the existing Native REST Service and not just a reference REST Service. This means that after a Virtual REST Service is created, any subsequent changes in the Native REST Service are not automatically propagated to the Virtual REST Service. This means that if you add Resource B to the Native REST Service, the newly added Resource B is not added to the already existing Virtual REST Service.

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

Versioning the REST Services: CentraSite Business UI allows versioning of Native REST Services and Virtual REST Services. You can make the following kinds of versions on the REST Services:

Create a new version of the existing Native REST Service, make the necessary changes to the new version, and then create a Virtual REST Service 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 Service.

Resynchronizing the REST Services: CentraSite Business UI allows resynchronization of the Virtual REST Services. This means that you copy the resource definition of the Native REST Service (which includes HTTP methods, parameters, or sample requests and responses) to the Virtual REST Service 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 Service.

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

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

When planning for the resource synchronization in Virtual REST Service, 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 Service, we recommend that you use the Virtualize action in the details page of that Virtual REST Service.

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

Be aware that only the additions and deletions at the resource-level are recognized by the Virtualize action during reconfiguration of a Virtual REST Service. 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 Service, the updated metadata of the Native REST Service will completely overwrite the existing metadata of the Virtual REST Service.

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

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

The Virtual REST Service 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 Service to include an additional metadata DELETE Method to the existing Resource B. The Native REST Service will now have the two resources with the following methods:

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

When you reconfigure the Virtual REST Service from the details page of the Native REST Service, 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 Services. However, on reconfiguring the Virtual REST Service, this difference of the method specification is not recognized in the user interface.

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

Important:
As a best practice, Software AG recommends that you maintain the Native REST Service as the single point of truth and synchronize all your changes with the Virtual REST Service using the synchronization process.

There are significant use cases that require real-time and accurate data synchronization. Consider a REST Service allows users access to a collection of resources through a Virtual REST Service. The goal is to keep the data on the Virtual REST Service synchronized with the data of Native REST Service. Types of use cases that are contemplated within the scope of the synchronization are exemplified by, but not limited to, the following scenarios:

Add Resource Usage Scenario: You choose to reconfigure an existing Virtual REST Service, and the Native REST Service indicates resources that have been introduced since the Virtual REST Service was initially created.

Edit Resource Usage Scenario: You choose to reconfigure an existing Virtual REST Service, and the Native REST Service indicates resources that are also available in the Virtual REST Service.

Delete Resource Usage Scenario: You choose to reconfigure an existing Virtual REST Service, and the Native REST Service indicates resources that have been deleted since the Virtual REST Service was initially created.

Combination Usage Scenario: You choose to reconfigure an existing Virtual REST Service, and the Native REST Service indicates resource metadata that has undergone various changes (modifications, additions, deletions) since the Virtual REST Service was initially created.

The outcome of each operation (edit, add, and delete) on the resource metadata is given based on a very simple instance configuration in each of the usage scenarios.

Add Resource Usage Scenario

In this scenario, CentraSite displays the Resource C which has been newly added to the Native REST Service with a unselected check box.

To allow synchronization of the newly added resource (that is, add the new Resource C to the Virtual REST Service), under the Recreate resources section, select the check box of the newly added Resource C, and click Next.

Edit Resource Usage Scenario

In this scenario, CentraSite displays the Resource A and Resource B that are available in both the Native REST Service and the Virtual REST Service with pre-selected check boxes.

To allow synchronization of the updated resource metadata (that is, include the modification to Resource B in the Virtual REST Service), under the Recreate resources section, retain the default check box selection, and click Next.

Delete Resource Usage Scenario

In this scenario, CentraSite displays the Resource B which has been deleted from the Native REST Service with a unselected check box.

To allow synchronization of the deleted resource metadata (that is, delete the Resource B from the Virtual REST Service), under the Resource differences section, select the check box of the Resource B you want to delete, and click Next.

Combination of Usage Scenarios

Native REST Service	Virtual REST Service
Resource A (deleted)	Resource A (differences)
Resource B (updated)	Resource B (already exists)
Resource C (added)	Resource C (newly added)

In this scenario, CentraSite displays the updated Resource B with a pre-selected check box, and the deleted Resource A and newly added Resource C with an unselected check box.

The resource synchronization mechanism can be best understood with the following table:

Use case	Recreate resources...			Resource differences
	Resource A	Resource B	Resource C	Resource A	Resource B	Resource C
Complete synchronization	N/A				N/A	N/A
Synchronize modified resource only	N/A				N/A	N/A
Synchronize added resource only	N/A				N/A	N/A
Synchronize deleted resource only	N/A				N/A	N/A
No synchronization	N/A				N/A	N/A

Key	Description
Native REST Service	An instance of the type REST Service
Virtual REST Service	An instance of the type Virtual REST Service

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