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.
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:
|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.|
|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.
2. Set routing mode for operations
For each operation, you would like to route, select the Routing Mode:
Possible values are –
|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.
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.
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 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.
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 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.