API Recorder

When API Recorder is running in proxy mode, API clients do not have to change the URLs where they submit their requests. The HTTP client library they use has to be configured to use the API Recorder as an HTTP/S proxy. The API client is unaware that requests are sent to the API Recorder first which then relays them to the API provider’s endpoint.

Consult the documentation of your HTTP client for how to configure the use of HTTP/S proxy.

API Recorder in router mode routes the incoming requests to pre-configured host and port number for the API provider. An API client has to be configured to submit its requests to a running API Recorder and not to the API provider.

In the future, we may add support for routing tables to allow the routing of HTTP traffic to more than one host and port number with a single instance of API Recorder.

The following optional environment variables control various aspects of configuring API Recorder:

In some environments, egress traffic to external API providers is always routed through a forward proxy. API Recorder can be configured to use such proxy when relaying requests to API providers over HTTP and HTTPS. For that to work, API Recorder must be running in proxy mode. This way, requests sent to API Recorder will contain the actual destination address.

The format for a proxy configuration value is [user[:password]@]host:port, where [] denotes an optional part in the configuration.

API Recorder uses hierarchical lookup to configure HTTP or HTTPS proxy. Here are the steps for HTTPS proxy - configuring HTTP proxy follows similar steps:

If accessing both HTTP and HTTPS URLs, then explicitly configure both HTTP and HTTPS proxies even if they are the same proxy.

Different tools have different rules for "no proxy" syntax.

API Recorder accepts a comma-delimited list of domains and IP addresses. The only wildcard no_proxy and NO_PROXY accept is a single * character, which matches "all hosts"; that effectively disables the proxy.

API Recorder does not accept * as a wildcard attached to a domain suffix. For example, this works:

However, this does not work:

The configuration

will match example.com and www.example.com.

Port numbers and CIDR ranges in a "no proxy" configuration are not supported.

Start an API Recorder instance on port 8880 and configure the directory where the traffic recordings will be saved. This example reuses the logs directory but usually you would specify your own location:

Linux:

Windows:

Notice that we did not specify -m argument so the recorder by default will run in proxy mode. The internal admin server by default will listen on port 8881.

Let’s submit a request using cURL to get a jQuery UI CSS file that is hosted by Google. The --proxy option tells cURL to use our recorder as a proxy:

Look in the directory with the recordings - there should be two new files created for the raw request (input) and response (output).

Let’s now submit a request using cURL to get the same jQuery UI CSS file as above but this time we will use https instead of http:

Notice the -k option - it tells cURL not to validate the certificate. Reason being - API Recorder was started without configuring a key store with Certificate and Private Key issued by a trusted CA (Certificate Authority) so it is using a self-signed Certificate bundled with the distribution.

The directory with the recordings should contain two new files with the actual raw request (input) to ajax.googleapis.com and its response (output) when accessed over HTTPS.

Stop the API Recorder before continuing with another example.

Use the -m argument to start API Recorder as a router:

Linux:

Windows:

The command tells API Recorder to route to ajax.googleapis.com:80 any request it receives.

Let’s now submit a request using cURL to fetch the jQuery UI CSS file as above but this time send the request to the API Recorder running on localhost, port 8880:

The directory with the recordings should have two new files - one for the request (input) and one for the response (output).

Stop the API Recorder before continuing with another example.

This assumes that all egress traffic for both HTTP and HTTPS is forced to go through a proxy proxy.example.com, port 8888. Requests to localhost, 127.0.0.1, and google.com and all its subdomains won’t be proxied.

Start an API Recorder instance on port 8880 and configure the directory where the traffic recordings will be saved. This example reuses the logs directory but usually you would specify your own location:

Linux:

Windows:

Notice that for this example we did not specify -m argument so the recorder by default will run in proxy mode but the concepts in this example apply to API Recorder running in router mode as well.

Let’s execute this HTTPS request:

The --proxy option tells cURL to use our API Recorder, running on localhost port 8880, as a proxy. The -k option is to configure cURL not to validate the proxy certificate.

By passing Accept-Encoding: gzip,deflate header, we advertise that our client can accept compressed response. If the server supports it, the HTTP body in the response will be compressed and the result printed on the screen will be that compressed HTTP body. The recorded response, however, will have the uncompressed content.

Similarly, we can execute the same request but over HTTP:

The example above demonstrated two features of API Recorder - configuring and using (forward) proxy, and dealing and capturing compressed responses. They can be configured and used independently of each other.

Stop the API Recorder before continuing with another example.

We would love to hear your feedback! Shoot us an email to [feedback at APISimulator.com] about anything that is on your mind.

Happy API Simulating!