Managing contracts

Save, list and delete contracts on the server.

The server stores every saved contract version. Use these endpoints to save new contracts, see what’s saved and remove contracts you no longer need.

Save a contract

Send the contract’s source as the plain-text body of POST /contracts:

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

The server parses the script before saving it. If it’s valid, the server responds with 201 Created:

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

• If the source has a syntax error, the contract isn’t saved and the server responds with 400 and a LexError or ParseError.
• If that path, name and version already exists, the server responds with 409 and a ContractExists error. Save it under a new version instead.

Saving only checks that the script parses. Problems that appear while running, such as a type mismatch or an unknown resource, are reported when the contract is invoked.

List contracts

GET /contracts returns every saved contract version with its parameters:

curl http://localhost:3000/contracts

{
  "contracts": [
    {
      "path": "greetings",
      "name": "Hello",
      "version": "1",
      "parameters": [{ "name": "name", "type": "string" }]
    },
    {
      "path": "greetings",
      "name": "Hello",
      "version": "2",
      "parameters": [
        { "name": "name", "type": "string" },
        { "name": "excited", "type": "boolean" }
      ]
    }
  ]
}

Delete a contract

Delete every version of a contract:

curl -X DELETE http://localhost:3000/contracts/greetings/Hello

Delete a single version by adding @<version>:

curl -X DELETE http://localhost:3000/contracts/greetings/Hello@1

A successful delete responds with 204 No Content. If no matching contract exists, the server responds with 404 and an UnknownContract error.

Deleting can’t be undone. Anyone invoking a deleted version, or the latest version after all versions are deleted, gets a 404.