Simulation API

The simulation API is a stable protected set of functionality and comprises low level composable units of functionality.

Request API

Extracting information out of simulation requests

  • (query-param "my-param")
    Get a specified query parameter out of the sim request
    Parameter Description Type
    p specific parameter String
  • (path-param "my-param")
    Get a specified path parameter out of the sim request
    Parameter Description Type
    p specific parameter String
  • (param :my-param)
    Get a specified parameter out of the sim request
    Parameter Description Type
    p specific parameter keyword
  • (form-param "my-param")
    Get a specified form parameter out of the sim request
    Parameter Description Type
    p specific parameter String
  • (body-param "my-param")
    Get a specified body parameter out of the sim request
    Parameter Description Type
    p specific parameter String
  • (route-param route-params)
    Get the last route parameter out of the sim request
    Parameter Description Type
    route-params route params datastructure map
  • (header "my-header")
    Get a specified header out of the sim request
    Parameter Description Type
    h specific header String
  • (valid-inputs?)
    Check if request is well formed according to codex specification. Used with an if or when form.
  • (validate (respond 200))
    Same sa valid-inputs? but creates a 400 error where validation fails.
    Parameter Description Type
    response a bespoke sim ext response structure Composite response form

Response API

Forming synchronous simulation responses

The most flexible (and low level) way to create responses in a sim extension is to create Ring responses. An example is listed below. 

{
  :status 200
  :headers {"Content-Type" "application/json"}
  :body "json string"
}

Or an example of reading a file to specify the body content: 

{
  :status 200
  :headers {"Content-Type" "application/json"}
  :body (qslurp "path/file.json")
}
  • (success)
    Gets a random success response for this endpoint from the codex
  • (error)
    Gets a random error response for this endpoint from the codex
  • (error 500)
    Gets a specified error response for this endpoint from the codex
    Parameter Description Type
    status specific error status code Int
  • (respond 200)
    Create a response with a specific status header
    Parameter Description Type
    status specific status code Int
  • (respond 200 :body-url "my-file.json")
    Create a response with a specific status header and body. Content type is inferred from file extension.
    Parameter Description Type
    status specific status code Int
    body-url path to file String
  • (qslurp "my-file.json")
    Read a supporting resource, converting relative path to absolute.
    Parameter Description Type
    path path to resource (passed as relative in sim ext). String

Payload Transport API

Sending synchronous and asynchronous payloads over different protocols.

We often need to send route data to different destinations synchronously and asynhronously as a result of receiving a request. We provide one low level API mechanism for doing this and several abstractions over this in the sim library.

  • (make-request :put "http://host:port/path" {:content-type "application/json" :body "something"})
    Sends a specified payload with a specified method to a given url
    Parameter Description Type
    method HTTP method keyword
    url fully qualified url String
    payload datastructure defining headers etc map

Simulation Utility Library

The simulation utility library is a set of utility functions built on top of the API. This functionality is intended as an example for you to build your own functionality. Library utilities provided out of the box are in protean-utils.sim.edn in the codex/sim extension directory.

Response Example Library

Forming synchronous simulation responses

  • (rsp 200)
    Create a response with a specific status code.
    Parameter Description Type
    status specific status code Int
  • (h-rsp 200 "/items/12")
    Create a response with a specific status code and location header.
    Parameter Description Type
    status specific status code Int
    hdr location header String
  • (jsn 200 "my response string")
    Create a response with a specific status header, "application/json" content type and body
    Parameter Description Type
    status specific status code Int
    body body content String
  • (txt 200 "my response string")
    Create a response with a specific status header, "text/plain" content type and body
    Parameter Description Type
    status specific status code Int
    body body content String

Payload Transport Example Library

  • (post "http://host:port/path" "something")

    Posts a specified payload to a given uri

    Assumes content type is the same as requests content type.

    Optional headers parameter.

    Parameter Description Type
    url fully qualified url String
    hdrs optional headers map
    payload datastructure defining headers etc map
  • (put "http://host:port/path" "something")

    Puts a specified payload to a given uri

    Assumes content type is the same as requests content type.

    Optional headers parameter.

    Parameter Description Type
    url fully qualified url String
    hdrs optional headers map
    payload datastructure defining headers etc map
  • (patch "http://host:port/path" "something")

    Patches a specified payload to a given uri

    Assumes content type is the same as requests content type.

    Optional headers parameter.

    Parameter Description Type
    url fully qualified url String
    hdrs optional headers map
    payload datastructure defining headers etc map