About Routing

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:

Click the image to enlarge it.

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.

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.

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:

Click the image to enlarge it.

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. Route to Live first routes a request to the virtual service. If the virtual service has this request configured, the response mapped for this request will be returned by the virtual service. If the virtual service does not have this request configured and cannot generate a match, the request is automatically routed to the live backend to fetch the live response. If the live backend fails to respond or times out, Route to Live can be configured to return a default response.
Route Non-Virtualized Requests	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.

1. Click the Manage Responses button under the Default Response dropdown.
2. In the Manage Route to Live Responses dialog, click Add New Response, then OK.
3. In the Add New REST Response dialog, enter the response name, then OK.
4. 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

Click the image to enlarge it.

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:

Click the image to enlarge it.

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:

Click the image to enlarge it.

3. (Optional) Enable response recording

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:

Click the image to enlarge it.

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:

Click the image to enlarge it.

Note: For information on what requests and responses are recorded, and on how the virtual service handles request parameters, see What Data Is Recorded.

• 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.