HTTP API

Every endpoint for running scripts and managing contracts.

A RequestScript server exposes these endpoints. Examples use http://localhost:3000 as the server address. Your server may also require authentication headers; ask its administrator.

Method and path	Body	Purpose
POST /run	Script text	Run a request script once
POST /contracts	Script text	Save a contract script
POST /run/<path>/<Name>	{ "parameters": { ... } }	Invoke the latest version of a contract
POST /run/<path>/<Name>@<version>	{ "parameters": { ... } }	Invoke a specific version of a contract
GET /contracts	None	List every saved contract version
DELETE /contracts/<path>/<Name>	None	Delete every version of a contract
DELETE /contracts/<path>/<Name>@<version>	None	Delete one version of a contract

In URLs, the dots of a contract’s path become slashes: shop.orders.LineTotal is /run/shop/orders/LineTotal.

Run a request

POST /run

Runs a request script once. Send the script source as the request body.

curl -X POST http://localhost:3000/run \
  --data-binary @- <<'EOF'
request HelloWorld {
    return "Hello World!"
}
EOF

Response 200

{ "returnValue": "Hello World!" }

Sending a contract script to this endpoint is rejected with 400 InvalidScript.

Save a contract

POST /contracts

Saves a contract script. Send the script source as the request body.

curl -X POST http://localhost:3000/contracts \
  --data-binary @- <<'EOF'
contract path.to.MyContract@2(param1: string) {
    return "Hello ${param1}!"
}
EOF

Response 201

{
  "path": "path.to",
  "name": "MyContract",
  "version": "2",
  "parameters": [{ "name": "param1", "type": "string" }]
}

• 409 ContractExists if that path, name and version is already saved.
• 400 InvalidScript if the script is a request rather than a contract.

Invoke a contract

POST /run/<path>/<Name> or POST /run/<path>/<Name>@<version>

Runs a saved contract. Without a version, the latest version runs. Send parameters as JSON under parameters. For a contract without parameters, send {} or no body.

curl -X POST http://localhost:3000/run/path/to/MyContract@2 \
  -H "Content-Type: application/json" \
  -d '{ "parameters": { "param1": "World" } }'

Response 200

{ "returnValue": "Hello World!" }

See Invoking contracts for how parameters are converted.

List contracts

GET /contracts

Lists every saved version of every contract.

Response 200

{
  "contracts": [
    {
      "path": "path.to",
      "name": "MyContract",
      "version": "2",
      "parameters": [{ "name": "param1", "type": "string" }]
    }
  ]
}

Delete a contract

DELETE /contracts/<path>/<Name> or DELETE /contracts/<path>/<Name>@<version>

Without a version, deletes every version of the contract. With a version, deletes only that version.

Response 204 with no body.

Errors

Every error response has the same shape:

{
  "error": {
    "type": "ParseError",
    "message": "A parameter list must not be empty; omit the parentheses instead (line 1)"
  }
}

Status	type	Meaning
400	LexError	The script contains invalid characters, strings or escapes.
400	ParseError	The script isn’t valid RequestScript.
400	ParameterError	A contract parameter is missing, unknown or has the wrong type.
400	InvalidScript	A contract was sent to /run, or a request was sent to /contracts.
400	InvalidVersion	The version after @ in the URL isn’t dot-separated numbers.
400	InvalidBody	The body isn’t valid JSON, isn’t a JSON object, or parameters isn’t an object.
404	UnknownContract	No contract matches the path, name and version.
404	NotFound	No endpoint matches the method and URL.
409	ContractExists	That contract version is already saved.
422	RuntimeError	The script failed while running.

See Errors for what causes script errors. A failing resource call is not an error response: it’s reported to the script, and the request still succeeds.