Invoking contracts

Call a saved contract over HTTP and pass its parameters as JSON.

Invoke a saved contract with a POST request to /run/ followed by its path and name. Pass parameters as a JSON object under the parameters key.

contract path.to.MyContract(param1: string) {
    return "Hello ${param1}"
}

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

{ "returnValue": "Hello World" }

Build the URL

Replace each dot in the contract’s path with a slash, and end with the contract’s name:

Contract	URL
contract path.to.MyContract	/run/path/to/MyContract
contract Standalone	/run/Standalone
Version 2 of shop.orders.LineTotal	/run/shop/orders/LineTotal@2

Without a version, the latest version runs. See Versioning.

Pass parameters

The request body is a JSON object with a parameters object inside it:

{
  "parameters": {
    "item": { "price": 9.99, "quantity": 2 },
    "taxRate": 0.0825
  }
}

• Every declared parameter must be supplied. Use null to pass no value.
• Parameters the contract doesn’t declare are rejected.
• For a contract without parameters, send {} or leave out the body entirely.

If a parameter is missing, unknown or has the wrong type, the server responds with 400 and a ParameterError:

{ "error": { "type": "ParameterError", "message": "Missing parameter 'taxRate'" } }

How JSON becomes RequestScript values

Each parameter is converted from JSON to its declared type:

Declared type	Accepted JSON
int32	A whole number within the int32 range, or a string containing one
int64	A whole number within the int64 range, or a string containing one
decimal, decimal(p, s)	A number, or a string containing one
boolean	true or false
string	A string
object	An object
[]T	An array whose elements are each accepted as T
Any type	null

Numbers aren’t converted to strings, strings aren’t converted to booleans, and so on. A value of the wrong kind is a ParameterError.

Sending large or precise numbers

JSON numbers lose precision in many clients once they go beyond about 15 significant digits. For int64 and decimal parameters, send the value as a string to keep every digit. Whole numbers larger than 9,007,199,254,740,991 must be sent as strings: sent as JSON numbers, they’re rejected with a ParameterError.

{
  "parameters": {
    "accountId": "9223372036854775807",
    "amount": "12345678901234567.89"
  }
}

Values inside objects

An object parameter has no declared types for its properties, so their types are inferred: whole numbers become int32, or int64 if they’re too big for int32, and other numbers become decimal.

The response

A successful invocation returns 200 with the script’s return value:

{ "returnValue": { "total": 21.62835, "note": "Taxed at 8.25%" } }

See JSON encoding for how each type appears in the response, and Errors for every error response.