Managing Virtual REST Services
Virtual REST services are created and designed through a process similar to virtual SOAP services. Sentinet provides a unified approach to virtual REST and SOAP services' design and management even though there are few subtle differences described in this chapter. For more details on how to design Sentinet virtual services, see the Managing Virtual SOAP Services chapter in this guide.
To add new Virtual REST service to a selected Repository Folder, right click selected Folder and select + Add->Virtual Service->REST menu option (you can also use Add tool bar button for the same function).
A new (empty) virtual service will be created. Provide a virtual service-friendly name and optional description. The service-friendly name must be unique within a given folder. Click the Save toolbar button to save Virtual Service. Virtual Service will be created in its first version in the Draft state.
Designing Virtual Services
Click the Design tab and drag-and-drop the physical service version that is to be virtualized by this virtual service.
Virtual and Virtualized Operations
By default, a virtual service maps all virtual and virtualized operations in an exact "one-to-one" mapping. That means that each virtual operation gets the same Uri template, HTTP headers and other API parameters as its virtualized operation.
Sentinet users can change the default one-to-one mapping to a very
different, custom mapping.
Modify [...] buttons located next to operation, request and
response tree items allow modification and custom mapping of the
respective API elements.
Design view shows virtual service operation items from the perspective of the virtual service client application, while endpoint(s) in the tree control indicate outbound endpoints of the virtual service used to call the physical (backend) service; modifying tree item properties will change the virtual, not the physical service. For example, renaming an operation will change name of the virtual operation, while physical (backend) operation remains as it was registered for the physical service.
Figure. Example of a physical Search operation renamed to Search2 in a virtual service and shown as Search2 (Search) operation.
Another example is clicking the [+] button located next to Responses item to add a new response description to the list of the documented operation's responses. In this case, a new Response will be added to the virtual service (but not to the physical (backend) service).
Details of how added (or modified) Response message properties can be defined, are described in the Response Properties chapter of this document.
The actual mapping between virtual and virtualized API properties is behind the properties of an operation's Request. Click Modify [...] button located next to Request tree element. Request Message Details dialog box opens full screen to accommodate more space to show properties of the Virtualized Request and Virtual Request. Note, that Virtualized Request properties cannot be changed on this dialog box, while Virtual Request properties can be changed to provide custom mapping between operation's requests. The dialog box size can be changed.
The Method property can be changed to provide a different mapping between a virtualized operation's HTTP method and a virtual operation's HTTP method. A virtual API may also change an original API semantic to make it better suited to a "standardized" syntax. For example, consider an original API designed to have two operations:
HTTP GET: http://server/myapi/action=create?orderDetails={orderDetails}
HTTP GET: http://server/myapi/action=delete?orderId={orderId}
A virtual API may change this sematic, so that these virtual operations are now defined as:
HTTP PUT: http://server/myapi?orderDetails={orderDetails}
HTTP DELETE: http://server/myapi?orderId={orderId}
A Virtual Operation Uri Template field can also be changed to provide a different mapping between virtual and virtualized operations' templates. Mapping is based on variable names matching. For example, if a virtualized Uri Template has a variable {query}, it will be mapped to the same variable {query} regardless of where it is found in the virtual Uri Template. (The new location might not even be in a query parameter, but in a Uri segment or an HTTP header instead).
Important
Uri Templates mapping is a frequently used, powerful feature to add security and services versioning aspects to REST APIs.
From the security perspective, it is common practice to embed security keys and tokens in operations’ URLs or HTTP headers. Virtual services may introduce security keys required from the consumer applications, while transforming these keys into different keys or even different security models required by the backend physical APIs (for example external security is based on API keys, while the internal security is Windows integrated based on integration with the internal Active Directory).
From the services versioning perspective, it is common to introduce new API versions that can potentially break compatibility with existing consumer applications. Virtual services can provide mappings and transformations that enable legacy applications to communicate with new API versions (Sentinet also supports many other services’ versioning mechanisms).
An Unknown Query Params property can be set to Pass-through or Ignore. A Pass-through value will allow unknown (not registered with the virtualized service) query parameters to flow through the virtual service to the backend service. An Ignore value instructs the virtual service to strip out unknown (unregistered) query parameters.
Important
The Ignore value can be particularly important when a backend physical API is fully described in the Repository with all its available query parameters. In this case, virtual services can protect the physical API from potential vulnerability attacks by preventing access to the backend API with unknown query parameters.
An Ignore Trailing Slash property controls the matching rules for the actual request messages and the Uri Template (see Request Properties chapter in this User Guide for more details on this property).
Note
Uri Template segments, Query Parameters and HTTP headers defined with variable values can participate in the dynamic mapping “interchangeably”. For example, an HTTP header value can be mapped to a Query Parameter value or a Uri Template segment, and vice versa.
Just as with SOAP services, REST APIs can be aggregated using a single virtual service providing API architectures with flexibility, agility and software reuse. The feature can be particularly important for architectures based on a Microservices paradigm.
(See the Designing Virtual Services chapter for more details on services aggregation feature).
Inbound and Outbound Endpoints
Virtual REST services’ inbound and outbound endpoints are configured similarly to SOAP virtual services, with the exception that REST endpoints are typically configured with RESTful policies (shared or private). Sentinet is shipped with some built-in “REST - …” shared policies for RESTful APIs. See the Inbound Endpoints and Outbound Endpoints chapters in this guide for more details on how to configure virtual service endpoints.
Virtual REST services may also be assigned Token Validation Keys for inbound endpoints, which require OAuth service policy and the policy requires knowledge of Token Validation Keys (signing secrets), and when these signing secrets are not configured using <signingSecrets> element.
Testing
Testing a virtual REST service is similar to testing a virtual SOAP service (see Testing chapter for SOAP services); the difference being the generation of Response Test Messages. REST service responses can be of any Content-Type, with any HTTP status return code, multiple HTTP headers and body. The Response Test Message dialog box provides an arbitrary assignment of these properties to a sample response message. Sentinet users will typically use copy/paste of their known (or expected) responses to assign Response Test Messages to a test set.
