Response Format

Rather than using a fully custom way of representing the resources we expose in Frontier, we use HAL. HAL is a hypermedia format in JSON that remains simple while giving us a couple of benefits such as simpler client integration for several languages. See this wiki page for a list of libraries.

At its simplest, a HAL response is just a JSON object with a couple of reserved property names: _links is used for expressing links and _embedded is used for bundling other HAL objects with the response. Other than links and embedded objects, HAL is just JSON.

HAL is a hypermedia format, like HTML, in that it has a mechanism to express links between documents. Let’s look at a simple example:

{
  "_links": {
    "self": {
      "href": "/ledgers/1"
    },
    "transactions": {
      "href": "/ledgers/1/transactions{?cursor,limit,order}",
      "templated": true
    }
  },
  "id": "43cf4db3741a7d6c2322e7b646320ce9d7b099a0b3501734dcf70e74a8a4e637",
  "hash": "43cf4db3741a7d6c2322e7b646320ce9d7b099a0b3501734dcf70e74a8a4e637",
  "prev_hash": "",
  "sequence": 1,
  "transaction_count": 0,
  "operation_count": 0,
  "closed_at": "0001-01-01T00:00:00Z",
  "total_coins": "100000000000.0000000",
  "fee_pool": "0.0000000",
  "base_fee_in_stroops": 100,
  "base_reserve_in_stroops": 100000000,
  "max_tx_set_size": 50
}

The above response is for the genesis ledger of the DigitalBits test network, and the links in the _links attribute provide links to other relavant resources in Frontier. Notice the object beneath the transactions key. The key of each link specifies that links relation to the current resource, and in this case transactions means “Transactions that occurred in this ledger”. Logically, you should expect that resource to respond with a collection of transactions with all of the results having a ledger_sequence attribute equal to 1.

The transactions link is also templated, which means that the href attribute of the link is actually a URI template, as specified by RFC 6570. We use URI templates to show you what parameters a give resource can take. You must evaluate the template to a valid URI before navigating to it.

Pages

Pages represent a subset of a larger collection of objects. As an example, it would be unfeasible to provide the All Transactions endpoint without paging. Over time there will be millions of transactions in the DigitalBits network’s ledger and returning them all over a single request would be unfeasible.

Read more about paging in following docs:

Streaming

Certain endpoints in Frontier can be called in streaming mode using Server-Sent Events. This mode will keep the connection to frontier open and frontier will continue to return responses as ledgers close. All parameters for the endpoints that allow this mode are the same. The way a caller initiates this mode is by setting Accept: text/event-stream in the HTTP header when you make the request. You can read an example of using the streaming mode in the Follow Received Payments tutorial.


Edit this doc in GitHub

THE FUTURE OF LOYALTY STARTS HERE

Stay up to date on the latest happenings at DigitalBits. Get the latest news.