Running API Simulator

Overview

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.

Starting and Stopping

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:

apisimulator start <api-simulation-directory>

For example:

apisimulator start /tests/apisims/payments-simulation

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:

apisimulator stop <api-simulation-directory>

The simulation directory is only needed for the stop command to assure that the log for the shutdown ends up in the simulation’s directory.

On Windows:

  • The API Simulator process runs in a new window.

  • stout and stderr are automatically redirected to a file named apisimulator.out in the log files directory if the log output is to a file.

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:

apisimulator start /apisims/hello-world > /apisims/hello-world/apisimulator.out 2>&1

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.

Multiple API Simulators

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

definition

There is no limitation on the number of API Simulator instances on a host - just use different port numbers for the API Simulators and their admin servers.

Command-line Arguments

API Simulator supports a number of arguments. Each command-line argument also has a respective JVM -D argument.

Command-line arguments are expected after the path to the simulation:

apisimulator start <api-simulation-directory> <command-line-arguments>

apisimulator stop <api-simulation-directory> <command-line-arguments>

The following table lists the supported arguments:

Command-line Argument JVM -D Argument Description

-h <arg>

apisimulator.host=<arg>

Simulator host. Useful when there are multiple network interfaces. Optional.

-p <arg>

apisimulator.port=<arg>

Simulator server port number. Optional.

-s <arg>

apisimulator.simlets.path=<arg>

Path to simulation configuration (directory). Automatically provided when using the apisimulator script.

-c <arg>

apisimulator.config.paths=<arg>

Comma-delimited list of hierarchical configuration directories. Automatically provided when using the apisimulator script.

-d <arg>

apisimulator.simlet.default=<arg>

Name of the default simlet. Must match the directory name of the default simlet. Optional. Use an empty string to have API Simulator forward unmatched requests when called as a HTTP or HTTPS (!) proxy.

-charset <arg>

apisimulator.simlet.charset=<arg>

Default charset. Optional.

-key_store <arg>

apisimulator.tls.keyStore=<arg>

File specification of Java key store (JKS) for configuring TLS. Use together with -key_store_password and -key_password as needed.

-key_store_password <arg>

apisimulator.tls.keyStore.password=<arg>

Java key store (JKS) password for configuring TLS. Use together with -key_store and -key_password as needed.

-key_password <arg>

apisimulator.tls.keyPassword=<arg>

Key password. Use together with -key_store and -key_store_password as needed.

-self_signed_cert_fqdn <arg>

apisimulator.tls.selfSignedCert.fqdn=<arg>

Fully qualified domain name (FQDN) for self-signed certificate issued at run-time. Use on its own to configure TLS.

-certificate <arg>

apisimulator.tls.certificate=<arg>

Certificate file in PEM format for TLS configuration. Use together with -private_key.

-private_key <arg>

apisimulator.tls.privateKey=<arg>

Private key file in PEM format for TLS configuration. Use together with -certificate.

-admin_host <arg>

apisimulator.admin.host=<arg>

Admin server host. Useful when there are multiple network interfaces.

-admin_key <arg>

apisimulator.admin.key=<arg>

Value of the key/passphrase, if the admin server is secured. Required to stop an API Simulator instance remotely if a key/passphrase was supplied at startup time.

-admin_port <arg>

apisimulator.admin.port=<arg>

Admin server port number.

-http_proxy <arg>

apisimulator.proxy.http=<arg>

Proxy to use when forwarding unmatched HTTP requests. See also Proxy Configuration.

-https_proxy <arg>

apisimulator.proxy.https=<arg>

Proxy to use when forwarding unmatched HTTPS requests. See also Proxy Configuration.

-no_proxy <arg>

apisimulator.noproxy=<arg>

Comma-delimited list of domains and IP addresses to exclude from proxying when forwarding unmatched HTTP or HTTPS requests. See also Proxy Configuration.

apisimulator.log=<arg>

The value determines the logging destination. See also Logging Configuration.

apisimulator.log.level=<arg>

The logging level. See also Logging Configuration.

apisimulator.log.fileName=<arg>

Fully qualified path and file name for the log file when the logging destination is a file. See also Logging Configuration.

start

Starts an API Simulator instance for a simulation.

stop

apisimulator.stop

Shuts down an API Simulator. Which API Simulator is stopped is determined by the port number of its admin server

<arg> is the argument’s value.

Examples

Run API Simulator on port 8080 and its admin server on port 8090:

apisimulator start <api-simulation-directory> -p 8080 -admin_port 8090

apisimulator stop <api-simulation-directory> -admin_port 8090

Run API Simulator on port 8000, its admin server on port 9999, and secure the admin server with a key:

apisimulator start <api-simulation-directory> -p 8000 -admin_port 9999 -admin_key 1^pnD0wn

apisimulator stop <api-simulation-directory> -admin_port 9999 -admin_key 1^pnD0wn

Run API Simulator on its default port 6090 and configure TLS using self-signed certificate issued at run-time:

apisimulator start <api-simulation-directory> -self_signed_cert_fqdn test.apisimulation.com

apisimulator stop <api-simulation-directory>

Environment Variables

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

Environment Variable Description

APISIMULATOR_JAVA

Makes it possible to start API Simulator using a Java installation different from the one JAVA_HOME points to.

APISIMULATOR_HEAP_SIZE

Maximum and/or minimum JVM heap size and other memory-related settings.

Linux, macOS:

export APISIMULATOR_HEAP_SIZE="-Xms512m -Xmx512m"

Windows:

set "APISIMULATOR_HEAP_SIZE=-Xms512m -Xmx512m"

APISIMULATOR_LOG

The value determines the logging destination. See also Logging Configuration.

APISIMULATION_LOG_FILE

Logging configuration file. See also Logging Configuration.

APISIMULATION_LOG_PATH

Path to the directory for the log files.

APISIMULATOR_LOG_FILENAME

Fully qualified path and file name for the log file when the logging destination is a file. See also Logging Configuration.

APISIMULATOR_LOG_LEVEL

The logging level. See also Logging Configuration.

APISIMULATION_SCRIPTS_DIRS

Allows specifying one or more comma-separated directories with scripting files.

APISIMULATOR_OPTS

Other JVM options and arguments except heap size. For example, Garbage Collector settings.

http_proxy

Proxy to use when forwarding unmatched HTTP requests. API Simulator itself must be called as a proxy. See also Proxy Configuration.

HTTP_PROXY

Proxy to use when forwarding unmatched HTTP requests, if http_proxy isn’t configured. See also Proxy Configuration.

https_proxy

Proxy to use when forwarding unmatched HTTPS requests. See also Proxy Configuration.

HTTPS_PROXY

Proxy to use when forwarding unmatched HTTPS requests, if https_proxy isn’t configured. See also Proxy Configuration.

no_proxy

Comma-delimited list of domains and IP addresses to exclude from proxying when forwarding unmatched HTTP or HTTPS requests. See also Proxy Configuration.

NO_PROXY

Comma-delimited list of domains and IP addresses to exclude from proxying when forwarding unmatched HTTP or HTTPS requests, if no_proxy isn’t configured. See also Proxy Configuration.

Important:

Whether using JAVA_HOME or configuring APISIMULATOR_JAVA, make sure that the path does not contain the bin directory!

Logging Configuration

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.

Configuration File

To set logging configuration file, set APISIMULATION_LOG_FILE environment variable with fully qualified path and file name, or just a file name. File name only can be specified if the file is located in one of the default locations per simulation. A configuration file provides a complete logging configuration.

If changing the logging configuration fie, it is recommended to use as a starting point a copy of the built-in logging configuration files found in the config installation directory. API Simulator uses Log4j 2, so see also its online documentation here.

By default, start and stop use different logging configuration files.

Logging Destination

The logging destination can be controlled by

  • JVM argument -Dapisimulator.log=<destination>, or

  • Environment variable APISIMULATOR_LOG=<destination>

…​where the JVM argument takes precedence over the environment variable.

The valid values for <destination> are: stdout for writing to the console; file for writing to a local file; or empty string to disable logging.

To preserve backward compatibility, the default destination is a log file.

Log File Name

To change the file to which API Simulator writes log entries when the logging destination is a file, use

  • JVM argument -Dapisimulator.log.fileName=<file>, or

  • Environment variable APISIMULATOR_LOG_FILENAME=<file>

…​where the JVM argument takes precedence over the environment variable.

In both cases <file> is expected to be fully qualified path and file name for the log file.

Logging Level

To change the logging level, use

  • JVM argument -Dapisimulator.log.level=<level>, or

  • Environment variable APISIMULATOR_LOG_LEVEL=<level>

…​where the JVM argument takes precedence over the environment variable.

The value for <level> can be one of error, warn, info, or debug; the default is info.

HTTPS Configuration

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:

  • Certificate and private key in PEM format.

  • Self-signed certificate issued at run-time by API Simulator for a fully qualified domain name (FQDN) of your choice.

  • Java KeyStore (JKS)

See the Command-line Arguments section for the respective start-up arguments.

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.

Proxy Configuration

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:

  1. Look for program argument https_proxy

  2. If https_proxy program argument was not found or it was empty, look for JVM -D argument apisimulator.proxy.https

  3. If JVM argument was not found or it was empty, look for environment variable https_proxy

  4. If environment variable https_proxy was not found or it was empty, look for environment variable HTTPS_PROXY

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 [user[:password]@]host:port, where [] denotes an optional part in the configuration.

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.

Example

Using program arguments, configure different proxies for HTTPS and HTTP requests:

-https_proxy proxy.example.com:4888 -http_proxy proxy.example.com:8888

Using program arguments, configure the same proxy for both HTTPS and HTTP requests:

-https_proxy proxy.example.com:8443 -http_proxy proxy.example.com:8443

No Proxy

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:

no_proxy=.example.com

However, this doesn’t work:

no_proxy=*.example.com

The configuration

no_proxy=.example.com

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

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

Access Logging

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:

  1. Check if -D JVM argument named apisimulator.accessLog is defined and has one of these case-insensitive values: stdout or file. Any other value will practically disable access logging.

  2. Check if environment variable named APISIMULATOR_ACCESS_LOG is defined and has one of these case-insensitive values: stdout or file. Any other value will practically disable access logging.

  3. Missing APISIMULATOR_ACCESS_LOG or -Dapisimulator.accessLog will practically disable access logging.

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.

Log Entry Format

An access log entry has the following format:

local-time-with-offset|ACCS|remote-address > local-address|http-method uri|status-code|response-length|simlet-name|delay|elapsed-time

where:

  • local-time-with-offset is the local time down to the milliseconds and contains the time zone offset like in 2019-01-25T11:13:28.103-0800.

  • ACCS denotes that the entry is an access log entry. This helps distinguish it from regular API Simulator log entries when both kinds are output to the console/stdout.

  • Both remote-address and local-address include IP address and port number. For example: 127.0.0.1:6090.

  • response-length is the size of the response body. Before, for HTTP/1.x, it was including the size of the status line and header fields as well. This now is more aligned with standard HTTP access logs. However, it is to note that in case of any premature connection closing due to a simulated connection disruption, the size may not match what the client ultimately receives.

  • simlet-name is for the simlet that was used to simulate the response to the request.

  • delay is any delay, per the simlet configuration, to simulate slow APIs/latency.

  • elapsed-time is the processing time to render and stream the response.

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!