Running API Simulator

A Standalone API Simulator instance is a Java process running in its own JVM (Java Virtual Machine). You don’t need to know Java to run API Simulator.

Assuming <api-simulation-directory> is the path to a directory with simulation configuration, a quick way to start an API Simulator instance for the simulation is to execute:

For example:

This command requires the current directory to be the bin directory under the simulator’s installation, or to have the full path to that directory already added to the PATH environment variable. Otherwise, use fully qualified path to the apisimulator script.

API Simulator will be listening on the default port 6090 and its admin server will be running on port 6190. Both API Simulator and its admin server are part of the same process and run in the same JVM (Java Virtual Machine).

The admin server listens for commands like the stop command to shut down the API Simulator remotely.

To stop the API Simulator started with the command above, execute:

The simulation directory is needed for the stop command to determine the proper way to locate and stop the right API Simulator instance (host, port number…​), and to assure that the log for the shutdown ends up in the simulation’s directory.

On Windows:

In some cases apisimulator.out could contain debugging information that may not be captured by the normal logging.

On Linux or Mac, it is up to you to redirect stout and stderr to a file, if you want. For example:

Using nohup and/or backgrounding the process on Linux or Mac (by adding & at the end of the command line) is also up to you.

Can multiple API Simulators run on the same host? Yes, absolutely:

API Simulator can be configured using command-line arguments, environment variables, or a configuration file. These methods can be combined - for example, set the port number using command-line argument and configure TLS in the configuration file.

Currently, some of the settings can be configured using command-line arguments and the simulation configuration file. When the same setting is passed in as a command-line argument and is also set the simulation configuration file, the value in the simulation configuration file "wins", takes precedence.

API Simulator’s logging can be controlled by making changes to its logging configuration file (not recommended), by providing a different logging configuration file, or by configuring some aspects of logging - logging destination, log file, and logging level - via environment variables or JVM arguments.

With API Simulator, you can mix both HTTP and HTTPS calls on the same port number. API Simulator dynamically detects HTTPS calls (HTTP over TLS) and does the necessary to complete the TLS handshake to establish a TLS connection.

By default, API Simulator will use the built-in self-issued certificate and private key. It is possible to configure a different certificate and key using one of these supported options:

See the Command-line Arguments section for the respective start-up arguments or the simulator’s tls settings in the Configuration File.

When using a self-signed certificate you may have to configure the calling application to accept it and trust it. How to do that depends on the application.

As described in On Request Mismatch, API Simulator can forward unmatched requests to the actual destination host. For that to work, API Simulator must be called as a HTTP or HTTPS proxy.

Forwarding unmatched requests may in turn require API Simulator to go through some HTTP or HTTPS proxy. This is typically seen in Enterprise environments. Below is how to configure API Simulator to use such proxy.

API Simulator uses hierarchical lookup to configure HTTP or HTTPS proxy to use when forwarding unmatched requests. 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.

The format for a proxy configuration value is [http[s]://][user[:password]@]host[:port], where [] denotes an optional part in the configuration. The type of proxy determines the protocol even when a scheme is specified with http:// or https://.

It is to note that API Simulator trusts all certificates when connecting to a HTTPS proxy or the actual destination host to forward unmatched requests.

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

API Simulator 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 Simulator does not accept * as a wildcard attached to a domain suffix. For example, this works:

However, this doesn’t work:

The configuration

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

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

To preserve backward compatibility, access logging is disabled by default. Configure it as explained below to enable it.

Access logging uses hierarchical configuration setup as follows:

If the target for the access log is a file, the file is placed in the same directory as the API Simulator’s log file. The log file name can be set by using the -Dapisimulator.accessLog.file=<file-name> JVM argument, or if that is not set, the APISIMULATOR_ACCESS_LOG_FILE environment variable. If the file name isn’t set using the aforementioned environment variable or JVM argument, it defaults to apisimulator-access.log.