API Simulation Configuration

Overview

The Standalone API Simulator is an awesome tool for simulating APIs that don’t exist yet, or APIs your applications depend on and require during development and testing. See API Simulator Editions for more details.

YAML-based DSL

Modeling API Simulations via configuration for the Standalone API Simulator is now easier than ever with our YAML-based DSL (Domain Specific Language).

XML (gasp!) configuration is still supported but please notice that it will be phased out in favor of the YAML (and perhaps JSON) DSL.

In addition, an option for visual modeling of API Simulations is our web browser-based API Simulation Modeler tool.

Few Words about YAML

YAML (YAML Ain’t Markup Language), per the description on its web site, is a "…​human friendly data serialization standard for all programming languages". It has gained wide acceptance as the language of choice for configuration.

YAML uses indentation-based scoping. In general, an element must be indented further than its parent element, and elements at the same level have the same indentation.

Indentation is very important - wrong indentation will lead to a malformed YAML document or may cause improper interpretation of the configuration.

Don’t worry if YAML is something new to you. API Simulator makes use of a small subset of the whole YAML language. More importantly, YAML is easy to understand and in no time you will be reading and writing API Simulation configuration in YAML. Here is a small example demonstrating possible configuration for matching HTTP requests that have "GET" method, and particular URI path and "Accept" header:

request:
- method: GET

- where: UriPath
  equals: "/api/v2/products"

- header: "Accept"
  contains: "/json"

Concise and expressive, no?

YAML and JSON

JSON is a subset of YAML 1.2 - a JSON document is also a YAML document.

While both languages can be used for human-friendly representation of data structures, arguably, YAML is more suitable for configuration and JSON for messaging.

In any case, we understand that some techies prefer JSON and we are planning to have support for JSON as well.

API Simulation Names

Each API Simulation has a name. A simulation name must be a valid subdomain name:

  • Starts with an a through z letter.

  • Then contains letters a through z, digits 0 through 9, and hyphen -, where hyphen is not the last character.

  • Has maximum length of 63.

  • Is case-insensitive.

These rules are currently not enforced; however, following them will assure backward compatibility in the future.

Creating New Simulation

For a new API Simulation simply create a directory and name it after the name of the simulation. Then create this minimalistic subdirectory structure (replace "api-simulation-name" with the name of your simulation):

api-simulation-name
└─ simlets

The simlets directory contains configuration for each simlet that is part of the simulation.

The following directory structure can help better represent and organize the configuration for more complex simulations:

api-simulation-name
├─ bin
├─ config
├─ lib
├─ logs
├─ scripts
└─ simlets

Here is a description of each directory:

Directory Description

bin

This optional directory can be a convenient place for custom scripts to start and stop the simulation. Such scripts could take care, for example, of setting all simulation-specific start and stop arguments.

config

Custom configuration, like for logging, can be placed in this directory. If the directory is missing, such configs can be placed directly under the simulation’s directory.

lib

API Simulator is extensible by custom code. Any compiled artifacts placed in this directory will be automatically added to the classpath.

logs

Log files will be created in this directory, if it exists. Otherwise, the log files will be created directly under the simulation’s directory.

scripts

If one or more of the simlets use scripting to enhance the API Simulator’s capabilities, files with the scripts can be placed in the "scripts" directory - API Simulator will automatically find and load them in memory at startup time.

simlets

Contains configuration for each simlet that is part of the simulation. The only required directory.

Simlets

An API Simulation consists of one or more simlets.

definition

A simlet simulates the HTTP response to an HTTP request.

The expressive YAML DSL (Domain Specific Language) of the Standalone API Simulator allows us to define simlets using simple and easy to understand constructs.

The configuration for each simlet is placed in a directory named after the simlet and under the simlets folder. There is always a file named simlet.yaml, which contains the simlet configuration.

For example:

payments-simulation
└─ simlets
   ├─ _default
   │  └─ simlet.yaml
   ├─ create-payment
   │  └─ simlet.yaml
   ├─ get-payment
   │  └─ simlet.yaml
   └─ list-payments
      └─ simlet.yaml

It is an option to have the HTTP Response body in a file, especially when it is binary content. Having a separate file also helps with simulations that return large responses, like with size measured in gigabytes.

Default Simlet

The example above shows a simlet named _default. By default, the response for that simlet will be returned if API Simulator cannot match an incoming HTTP request.

It is possible to change the behavior on unmatched HTTP requests - see "Request Forwarding" below.

Request Forwarding

This functionality is not currently exposed via the YAML DSL.


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!