Running API Simulator

Overview
Starting and Stopping
Multiple API Simulators
Command-line Arguments
- Examples
Environment Variables

Overview

A Standalone API Simulator instance is a Java process running in its own JVM (Java Virtual Machine).

Starting and Stopping

Assuming <api-simulation-directory> is the path to a directory with simulation configuration, 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 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.

Multiple API Simulators

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

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 to be specified after the path to the simulation:

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

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

Here is a table with the supported arguments:

Command-line Argument JVM -D Argument Description

Command-line Argument	JVM -D Argument	Description
`-h <arg>`	`apisimulator.host`	Simulator host. Useful when there are multiple network interfaces. Optional.
`-p <arg>`	`apisimulator.port`	Simulator server port number. Optional.
`-s <arg>`	`apisimulator.simlets.path`	Path to simulation configuration (directory). Automatically provided when using the `apisimulator` script.
`-c <arg>`	`apisimulator.config.paths`	Comma-delimited list of hierarchical configuration directories. Automatically provided when using the `apisimulator` script.
`-scripts <arg>`	`apisimulator.scripts`	Comma-delimited list of paths to directories with scripts. Surround with double quotes paths that contain spaces. Automatically provided when using the `apisimulator` script.
`-d <arg>`	`apisimulator.simlet.default`	Name of the default simlet. Must match the directory name of the default simlet. Optional.
`-charset <arg>`	`apisimulator.simlet.charset`	Default charset. Optional.
`-key_store <arg>`	`apisimulator.tls.keyStore`	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`	Java key store (JKS) password for configuring TLS. Use together with `-key_store` and `-key_password` as needed.
`-key_password <arg>`	`apisimulator.tls.keyPassword`	Key password. Use together with `-key_store` and `-key_store_password` as needed.
`-self_signed_cert_fqdn <arg>`	`apisimulator.tls.selfSignedCert.fqdn`	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`	Certificate file in PEM format for TLS configuration. Use together with `-private_key`.
`-private_key <arg>`	`apisimulator.tls.privateKey`	Private key file in PEM format for TLS configuration. Use together with `-certificate`.
`-admin_host <arg>`	`apisimulator.admin.host`	Admin server host. Useful when there are multiple network interfaces.
`-admin_key <arg>`	`apisimulator.admin.key`	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`	Admin server port number.
`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

-h <arg>

apisimulator.host

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

-p <arg>

apisimulator.port

Simulator server port number. Optional.

-s <arg>

apisimulator.simlets.path

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

-c <arg>

apisimulator.config.paths

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

-scripts <arg>

apisimulator.scripts

Comma-delimited list of paths to directories with scripts. Surround with double quotes paths that contain spaces. Automatically provided when using the apisimulator script.

-d <arg>

apisimulator.simlet.default

Name of the default simlet. Must match the directory name of the default simlet. Optional.

-charset <arg>

apisimulator.simlet.charset

Default charset. Optional.

-key_store <arg>

apisimulator.tls.keyStore

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

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

-key_password <arg>

apisimulator.tls.keyPassword

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

-self_signed_cert_fqdn <arg>

apisimulator.tls.selfSignedCert.fqdn

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

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

-private_key <arg>

apisimulator.tls.privateKey

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

-admin_host <arg>

apisimulator.admin.host

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

-admin_key <arg>

apisimulator.admin.key

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

Admin server port number.

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

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

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="-Xms256m -Xmx256m"` Windows: `set "APISIMULATOR_HEAP_SIZE=-Xms256m -Xmx256m"`
`APISIMULATION_LOG_FILE`	Logging configuration file - fully qualified path and name, or just file name. File name only can be specified if the file is located in one of the default locations per simulation. By default, start and stop use different logging configuration files.
`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.

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="-Xms256m -Xmx256m"

Windows:

set "APISIMULATOR_HEAP_SIZE=-Xms256m -Xmx256m"

APISIMULATION_LOG_FILE

Logging configuration file - fully qualified path and name, or just file name. File name only can be specified if the file is located in one of the default locations per simulation. By default, start and stop use different logging configuration files.

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.

We would love to hear your feedback! Shoot us a quick email to [feedback at APISimulator.com] to let us know what you think.

Happy API Simulating!