request:
- method: GET
- where: UriPath
equals: "/api/v2/products"
- header: "Accept"
contains: "/json"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:
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
athroughzletter. -
Then contains letters
athroughz, digits0through9, 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
└─ simletsThe 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
└─ simletsHere is a description of each directory:
| Directory | Description |
|---|---|
|
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. |
|
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. |
|
API Simulator is extensible by custom code. Any compiled artifacts placed in this directory will be automatically added to the classpath. |
|
Log files will be created in this directory, if it exists. Otherwise, the log files will be created directly under the simulation’s directory. |
|
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. |
|
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.
|
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.yamlIt 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.