Admin APIs

Overview

Starting an API Simulator instance also starts an Admin HTTP Server in the same process but on a different port number. The Admin Server enables the management of the API Simulator and API Simulations via API calls over HTTP/S.

By default, the Admin Server requires an API key with each request. The API key the Admin Server expects can be defined (preferably) in the admin section in the Configuration File or using a Command-line Argument.

All API endpoints start with /api followed by the version, like in /api/v1. The idea is to introduce in the future, say, /ui for calls to the backend of an Admin UI frontend.

Path parameters, like the simulation or simlet names, are case-sensitive.

Successful responses, even with an empty body, return 200 (OK) instead of a 204 (No Content) to keep it open to start returning payload in the future.

The Admin Server logs each request it receives at INFO level in the form of Access Log similar to the one used by API Simulator.

To ensure easy transition to future versions of the APIs, make sure that the client is capable of ignoring unrecognized fields without erroring out.

Simulations API

Create Simlets

POST /api/v1/apisims/{simName}/simlets

Parameters:

Type Name Value Req'd

header

APISIMULATOR-API-KEY

API key to authenticate to the Admin Server

Yes

header

Content-Type

application/apisim+yaml

Yes

path

simName

Name of the simulation in which to create simlets.

Yes

Request Body:
YAML document with simlet definitions, each definition separated from the next with --- document separator on a new line. Every simlet must have a valid name in the simlet element. Existing simlet with that name will be completely replaced, or a new simlet added otherwise.

Responses:

Code Description

201

Created. The simlets have been successfully created - added or updated - in the given simulation.

400

Bad Request. The body contains a JSON-formatted error message. For example:
{"errors": [{"msg": "Unrecognized content type header 'application/xml'"}]}

401

Unauthorized. Missing API key header or invalid key.

404

Not Found. The body contains a JSON-formatted error message. For example:
{"errors": [{"msg": "Simulation 'my-awesome-sim' not found in this API Simulator"}]}

500

Internal Server Error. The body contains a JSON-formatted error message. Please contact us about any such unexpected server error.

Uploading external files for simlet response body, list from file, parameter from file, CSV or SQL data sources, or scripts is not currently possible. With the exception of SQL data sources, the alternative is to embed them in the simlet configuration.

List All Simlets

GET /api/v1/apisims/{simName}/simlets

Parameters:

Type Name Value Req'd

header

APISIMULATOR-API-KEY

API key to authenticate to the Admin Server

Yes

path

simName

Name of the simulation which simlets to list.

Yes

Responses:

Code Description

200

OK. The body contains JSON-formatted list of simlets with just the simlet names for now. For example:

{"simlets": [
  {"simlet": "howdy"},
  {"simlet": "random-greeting"},
  {"simlet": "hi"},
  {"simlet": "apisimulator-simlet-404"},
  {"simlet": "apisimulator-proxy-connect"},
  {"simlet": "hello-world"},
  {"simlet": "greetings"}
]}

401

Unauthorized. Missing API key header or invalid key.

404

Not Found. The body contains a JSON-formatted error message. For example:
{"errors": [{"msg": "Simulation 'my-awesome-sim' not found in this API Simulator"}]}

500

Internal Server Error. The body contains a JSON-formatted error message. Please contact us about any such unexpected server error.

Many things go into storing a simlet’s definition internally to provide fast performance in a thread-safe way and avoiding some kind of lookups performed all the time to get configuration values. There are also the reference-by-name dependencies, like parameters or script executors, which get resolved once and replaced with reference-by-value…​
Long story short, there is not a good way to re-create an original simlet definition without stashing it away for any other reason but to return it in response to this API call. Therefore, for now, this API operation returns the simlet names only.

Remove a Simlet

DELETE /api/v1/apisims/{simName}/simlets/{simletName}

Parameters:

Type Name Value Req'd

header

APISIMULATOR-API-KEY

API key to authenticate to the Admin Server

Yes

path

simName

Name of the simulation from which to remove the simlet.

Yes

path

simletName

Name of the simlet to remove from the given simulation.

Yes

Responses:

Code Description

200

OK. The simlet has been successfully removed.

401

Unauthorized. Missing API key header or invalid key.

404

Not Found. The body contains a JSON-formatted error message. For example:
{"errors": [{"msg": "Simulation 'my-awesome-sim' not found in this API Simulator"}]}
or
{"errors": [{"msg": "Simlet 'my-simlet' not found"}]}

500

Internal Server Error. The body contains a JSON-formatted error message. Please contact us about any such unexpected server error.

Remove All Simlets

DELETE /api/v1/apisims/{simName}/simlets

Parameters:

Type Name Value Req'd

header

APISIMULATOR-API-KEY

API key to authenticate to the Admin Server

Yes

path

simName

Name of the simulation which simlets to remove.

Yes

Responses:

Code Description

200

OK. The simlets have been successfully removed. The body contains a JSON-formatted recap of the result. For example:

{ "result": {
    "simletsCount": 6,
    "removedCount": 6
  }
}

401

Unauthorized. Missing API key header or invalid key.

404

Not Found. The body contains a JSON-formatted error message. For example:
{"errors": [{"msg": "Simulation 'my-awesome-sim' not found in this API Simulator"}]}

500

Internal Server Error. The body contains a JSON-formatted error message. Please contact us about any such unexpected server error.

This operation removes all simlets from a given simulation, including the API Simulator’s built-in simlets loaded at startup time. The simulation itself still exists after this operation is successful and new simlets can be added to it via Create Simlets.

Simulator API

Stop API Simulator

DELETE /api/v1/simulator

Parameters:

Type Name Value Req'd

header

APISIMULATOR-API-KEY

API key to authenticate to the Admin Server

Yes

Responses:

Code Description

202

Accepted. The request has been received and the process of gracefully shutting API Simulator down may still be carried on as it may take up to a second or so.

401

Unauthorized. Missing API key header or invalid key.

404

Not Found. The body contains a JSON-formatted error message. For example:
{"errors": [{"msg": "Simulation 'my-awesome-sim' not found in this API Simulator"}]}

500

Internal Server Error. The body contains a JSON-formatted error message. Please contact us about any such unexpected server error.

Stopping API Simulator also stops the Admin Server and shuts down everything, including the whole running process.

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!