About Routing
About
Routing means that a virtual service (virtual API) forwards incoming requests to some real web service, gets response from it and transfers this response back to the client. That is, when routing is enabled, the virtual service is functioning as a transparent proxy between the client and some real API.
To route incoming requests, the service replaces the server name, port, and path in the URL with another address, port, and path that are set by the service settings. The resource part of the URL and query parameters (if used) remain unchanged:
 |
You can configure your virtual service to route all incoming requests or only some of them (see below). If needed, you can use conditional routing for some requests.
Why Routing?
Routing helps you –
Enhance your API on top of your existing operations. Suppose you are designing another version of your existing API. To test it, you create a new virtual service and route “existing” operations to your existing real web service. After that, you have to virtualize only new operations.
Smoothly transition your client code from a virtual service to a real API without changing the client code. Suppose you created a virtual service that mocks some API. You use this service to create client code or tests for that API until the API server part is ready. When developers complete some “real” server-side operations, you route matching virtual operations to them. After some more “real” operations are ready, you route more virtual operations, and continue doing this until all the “real” operations are ready. This approach helps you avoid changes in the client code or tests during development.
You can also command your virtual service to route requests and record non-virtualized operations at the same time. This helps you –
Add operations from a real API to your virtual service easily. ReadyAPI creates virtual operations from the recorded traffic. See Add Recorded Operations to Virtual Service.
Quickly create an entire virtual API from a real API. See Recording Virtual Services (New Virtual API Wizard), for example.
Explore “real” responses and create or modify your virtual services with ease. By enabling routing and recording, you can easily see what responses your real API sends to the clients and use these responses as a base for virtual responses of your virtual API.
Setting Up Routing
To enable routing for one or all operations of your virtual service, open the service editor and set the following options:
1. Set the service route options
From the Route Options drop-down list, select how the service should route requests (see the table below for details on each option). In the Route to field, enter the URL of the target API.
 |
Value | Description |
|---|---|
None | Routing is off. The virtual service processes operations according to their Dispatch settings. |
Route to | The virtual service routes incoming requests for which it has virtual operations. |
Route to Live | This setting controls the runtime behavior of a virtual service, deciding whether a response is sent from the virtual service or the live backend.
For full setup instructions, proxy configuration (Java 11+), timeout handling, and limitations, see Route to Live. |
Route Non-Virtualized Requests | The virtual service routes all incoming requests, including those for which it has no virtual operations. Virtual operations are processed in accordance with the Routing and Dispatch settings. |
Route and Record Non-Virtualized Requests | The virtual service routes all incoming requests and automatically creates virtual operations for the requests for which it has no operations yet. It records both request and response data. Note: This mode is not supported for recording authentication requests to servers that use Kerberos authentication. See the possible workaround. |
Route and Record for Conditional Match | The virtual service routes all incoming requests and automatically creates virtual operations for requests without existing operations. It records both request and response data and creates the related Conditional Match and Signature. For detailed setup, see Route and Record for Conditional Match. |
2. Set routing options for operations
For each operation, you would like to route, select the Routing Options:
 |
Possible values are –
Value | Description |
|---|---|
None | Routing is off for the operation. The virtual service processes the operation using the Dispatch settings. |
All | Routing is on for the operation. The virtual service routes all incoming requests to the target API. |
Conditional | Routing is on for the operation. For each incoming request, ReadyAPI runs a Groovy script to determine if the request should be routed or not. See Conditional Routing. |
You can change the Routing Mode setting for multiple operations in the following way:
 |
3. (Optional) Enable response recording
The virtual service captures responses from the existing API while routing. You can save these responses for future use. See Recording Responses below for more details.
Note
We recommend this option when using Route and Record for Conditional Match scenarios.
Recording Requests and Responses
In ReadyAPI, virtual services can record both requests and responses.
Request recording
To enable request recording, select the Route and Record Non-Virted Requests route option for your virtual service:
 |
When you select this option, the service saves data of incoming requests for which it has no virtual operations yet. The service also saves responses that it receives from the existing API for these requests. This feature helps you easily create virtual operations for the existing API operations. See Add Recorded Operations to Virtual Service.
Response recording
You can also record responses from a real API. This feature works for any route option and is helpful when you need to add real API responses to your virtual service.
To enable response recording, simply select the Record Responses check box for the desired “routed” operation:
 |
Note
For information on what requests and responses are recorded and on how the virtual service handles request parameters, see What Data Is Recorded .
Limitations
Routing works for REST, SOAP, and JDBC virtual services. It is not available for JMS virtual services.
If you use routing for some virtual service, then this service cannot run simultaneously with other services on the same computer. If you start this virtual service when some other service is running, ReadyAPI reports an error. Similarly, it reports an error when you start some other virtual service while your routing service is working.
To bypass this limitation and run multiple virtual services that use request routing, install VirtServer on your computer or on a remote machine and run the services in VirtServer.
Due to the specifics of the Kerberos authentication, the Route and Record Non-Virtualized Requests mode does not correctly record authentication requests to the servers that use this authentication type. You can try using a workaround for this.
In order to route and record SOAP traffic, you need to import the WSDL file into APIs part of your ReadyAPI project.