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) will 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 will 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 will help you avoid changes in the client code or tests during the development.
You can also command your virtual service to route requests and record non-virtualized operations at the same time. This will help you –
-
Add operations from a real API to your virtual service easily. ReadyAPI will create 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 routing options
Select one of the routing modes from the Routing Options drop-down list (see below for information on differences), and enter the URL of the target API to the Route to edit box:
Value | Description |
---|---|
None | Routing is off. The virtual service processes operations according to their Dispatch settings. |
Route to | The virtual service will route 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.
|
The virtual service will route all incoming requests, including those for which it has no virtual operations. Virtual operations will be processed in accordance with the Routing and Dispatch settings. | |
Route and Record Non-Virtualized Requests | The virtual service will route all incoming requests and will automatically create virtual operations for the requests for which it has no operations yet. It will record both request and response data.
Note: This mode is not supported for recording authentication requests to servers that use Kerberos authentication. See possible workaround. |
Configure Route to Live
Route to Live: The virtual service will route incoming requests for which it has no virtual operations. Virtual operations will be processed in accordance with the Routing and Dispatch settings, and when no match is found, the request is routed to the live service.
For Conditional Match
Request is received by ReadyAPI or VirtServer.
- Signature–Match + Data Values–Match
Response: The specific (exact match) response is returned from the virtual service.
- Signature–Match + Data Values–No Match
Response: A meta (signature-level default) response is returned from the virtual service.
- Signature–No Match (Not Found)
Request Routed: The request is routed to the live system to fetch the live response.
- No Response
If no signature match, no data match, or no response is received from the live system, a generated response is returned.
Default Response Configuration When Live Is Not Responding
You can configure a default response to be returned when the live system does not respond. This response will be used when no match is found or when the live system fails to provide a response within the configured timeout limits.
- Click the Manage Responses button under the Default Response dropdown.
- In the Manage Route to Live Responses dialog, click Add New Response, then OK.
- In the Add New REST Response dialog, enter the response name, then OK.
- In the Route to Live Response Editor, select the HTTP status code, content/media type, and other fields as needed. Confirm with OK.
Configurable Timeout Behaviors for Route to Live
Users can configure the timeout settings to control how the virtual service handles live routing:
- Gateway Socket Timeout
Sets the overall timeout for attempting to retrieve a response from the live system (for example, 10,000 ms).
- Per Attempt Timeout
Specifies the timeout per individual attempt to retrieve a response (for example, 500 ms).
- Maximum Number of Retries
Determines the maximum number of retry attempts to fetch a response (for example, 10).
Connection Settings for Route to Live
When configuring the Route to Live feature, the following connection settings are available:
Setting | Description | Example Value |
---|---|---|
Name | A unique identifier for the connection settings. | MyLiveServerConnection |
Target Server | The hostname or IP address of the live server. | live.example.com |
Target Port | The port of the live server. | 8080 |
Keystore Location | The file path to the keystore containing the certificates. | /path/to/keystore.jks |
Keystore Password | The password used to access the keystore. | password123 |
Connection Timeout (ms) | Maximum time to wait for a connection to be established. | 10000 |
Max Retries | Maximum number of connection retry attempts on failure. | 3 |
Socket Timeout (ms) | Maximum time to wait for data on the socket. | 5000 |
Logic
If the maximum number of retries and per attempt timeout fail to retrieve a response, or if the gateway timeout is reached with no response from the live backend, the virtual service returns a generated response based on the following:
- No signature match.
- No data match.
- No response from the live system.
Limitations
-
REST-Only Support: The Route to Live setting works for REST virtual services.
-
No Recording Mode: The Route to Live setting does not support a recording mode.
2. Set routing mode for operations
For each operation, you would like to route, select the Routing Mode:
Possible values are –
Value | Description |
---|---|
None | Routing is off for the operation. The virtual service will process the operation using the Dispatch settings. |
All | Routing is on for the operation. The virtual service will route all incoming requests to the target API. |
Conditional | Routing is on for the operation. For each incoming request, ReadyAPI will run 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 easily:
3. (Optional) Enable response recording
When routing requests, the virtual service is receiving responses from an existing API. You may save these responses to the service, if needed. See below for details.
Recording Requests and Responses
In ReadyAPI, virtual services can record both requests and responses.
Request recording
To enable request recording, you select the Route and Record Non-Virted Requests routing mode for your virtual service:
In this mode, the service will save data of incoming requests for which it has no virtual operations yet. The service will also save responses that it receives from the existing API to 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 of real API. This feature works for any routing mode and is helpful when you need to add real API responses to your virtual service.
To enable response recording, simply select the Recorded Response 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 TCP, 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 will report an error. Similarly, it will report 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 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.