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.

CORS

Cross-Origin Resource Sharing (CORS) requests are handled automatically.

The response to a pre-flight OPTIONS request is 204 (No Content) status and CORS headers that specify that all origins, methods, and headers are allowed.

For other requests that contain an Origin header, its value is simply echoed in an Access-Control-Allow-Origin header in the response.

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.

Get a Simlet

The operation retrieves the DSL model (definition) of a simlet. Notice that for this to work, the API Simulator must be started with the -retain_dsl_models option or the -Dapisimulator.simlet.retainDslModels JVM argument. See also Command-line Arguments.

GET /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

Yes

path

simletName

Name of the simlet from the given simulation which DSL definition to retrieve

Yes

Responses:

Code Description

200

OK. The response body contains a JSON object like this:

{
  "simlet": "<simlet-name>",
  "model": {
    "dsl": "<the simlet's DSL model>",
    "media": "application/apisim+yaml"
  }
}

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.

Here’s an example for a response:

{
  "simlet": "random-greeting",
  "model": {
    "dsl": "simlet: random-greeting\r\n\r\nrequest:\r\n- method:
 GET\r\n- uriPath: /hey\r\n\r\nGreeting:\r\n  is: parameter\r\n  from: list\r\n  list: [ 'Hi', 'Hello', 'Hey', 'Howdy' ]\r\n  pick: 1\r\n\r\nresponse:\r\n  from
: template\r\n  body: ${ Greeting }\r\n",
    "media": "application/apisim+yaml"
  }
}

The dsl field contains the DSL model. It is JSON-encoded so that special characters for JSON like double quotes and new lines are properly escaped.

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 the simlets names. 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.

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.

Reload Simulation

Reloading an API Simulation restores the initial state of simulation’s simlets by reloading the simulation and its simlets definitions as they were when the API Simulator was started. Any simlet that has been added will be lost.

PATCH /api/v1/apisims/{simName}

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 simulation was successfully reloaded.

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.

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 - send us a quick email to [feedback at APISimulator.com]

Happy API Simulating!