Versioning

Declare contract versions, publish changes as new versions and invoke a specific version.

Contracts are immutable. Once a version of a contract is saved, it can’t be changed. To change a contract, save the whole contract again under a new version. Callers that need stable behavior can pin a version, and everyone else gets the latest.

Declare a version

Write the version after the contract name, with @:

contract greetings.Hello@2(name: string) {
    return "Hi ${name}!"
}

• A version is one or more dot-separated numbers with no spaces: @2, @1.5, @1.2.3 or deeper.
• If you leave out the version, it’s 1.

A contract is identified by its path, name and version together. Saving a path, name and version that already exists is rejected with 409 Conflict:

{
  "error": {
    "type": "ContractExists",
    "message": "Contract 'greetings.Hello@2' already exists; contracts are immutable — save it again with a new version"
  }
}

Publish a change

1. Start from the current contract

   contract greetings.Hello(name: string) {
       return "Hello ${name}!"
   }
   

   With no version, this is version 1.

2. Edit it and give it a new version

   contract greetings.Hello@2(name: string, excited: boolean) {
       if (excited) {
           return "Hello ${name}!!!"
       }
       return "Hello ${name}."
   }
   

   A new version can change anything, including its parameters.

3. Save it

   Send it to POST /contracts. Version 1 stays available, and version 2 becomes the latest.

Invoke a version

Invoking a contract without a version runs the latest version:

POST /run/greetings/Hello

Add @<version> to the URL to run a specific version:

POST /run/greetings/Hello@1

Because the latest version can change its parameters, clients that depend on a particular set of parameters should invoke a specific version.

How versions are ordered

The latest version is found by comparing versions numerically, one segment at a time, from left to right:

• @1.10 is newer than @1.9, because 10 is greater than 9.
• @2 is newer than @1.99.99.
• A missing segment counts as 0 when comparing, so @1.0.1 is newer than @1.

Versions are matched exactly

When you save or invoke a specific version, it’s matched exactly as written. @1, @1.0 and @1.0.0 are three different versions. If you saved @1.0, invoke it as /run/greetings/Hello@1.0, not @1.

To avoid confusion, pick one versioning style per contract, such as always using a single number (@1, @2, @3) or always using three segments (@1.0.0, @1.1.0).

Delete versions

You can delete a single version or every version of a contract. See Managing contracts.