Skip to main content

1. Overview

The Cordial Treasury API is a

  • collaborative
  • permissioned
  • resource-oriented
  • REST API

All client-visible state is modeled as resources which offer CRUD operations via HTTP. Collaborative means that each CRUD operation request originates from a user of the system, signed with one of the credentials registered for this user, and possibly approved by other users adding their signature. Permissioned means that there is a granular access policy in place, determining which CRUD operations are allowed for which users under which circumstances. The active access policy consists of rules, which themselves are resources that can be modified. On top of this, certain resources (currently: the transfer policy for transfers) have their own policy, which further regulates the values of the resources.

Names and Resources​

Each resource has a globally unique, immutable name. For instance, users/joe refers to a User resource, or chains/ETH/addresses/0x1f9090aaE28b8a3dCeaDf281B0F12828e676c326 refers to an Address on the Chain named chains/ETH. Any resource can by read by sending a GET request to the API endpoint, with the name as path. For instance, the Cordial Gateway returns user Joe via GET of https://treasury.cordialapis.com/v1/users/joe.

Operations on Resources​

CRUD operations are initiated by HTTP requests to an appropriate endpoint. Creation uses POST, reading uses GET, updating uses PUT, and deletion uses DELETE. To create or update, the request payload is a JSON representation of the resource. Errors are signaled by an HTTP error status code, in which case the Error type is returned. Due to the collaborative nature of the API, responses are not directly JSON representations of resources, but instead the OperationName of the Operation it initiated (or approved), typically in either the authorizing or succeeded state. Clients repeatedly read the returned operation by its name, until it is in a terminal state (succeeded or failed). In the successful case, the response includes the name of the resource just created or updated, which can then be fetched with a `GET~.