1. Overview

The Easy Blockchain API is an easy to use API to store related entries within chains. Currently it stores entries using a Factom, Ethereum or Multichain blockchain.
For full API documentation please visit: https://docs.sphereon.com/api/easy-blockchain/0.10/html
Interactive testing: A web based test console is available in the Sphereon API store at: https://store.sphereon.com

1.1. Version information

Version : 0.10

1.2. Contact information

Contact : Sphereon DevOps Team
Contact Email : dev@sphereon.com

1.4. URI scheme

Host : gw.api.cloud.sphereon.com
BasePath : /blockchain/easy/0.10
Schemes : HTTPS

1.5. Tags

  • All : All Blockchain APIs

  • Backend : Backend related APIs

  • Chain : Chain related APIs

  • Context : Context and backend related APIs

  • Entry : Entry related APIs

  • Id : Id determination and existence APIs

2. Introduction

The Sphereon Easy Blockchain API provides a blockchain agnostic solution especially useful for immutable data storage. The key benefits are:

  • Immutable storage of content

  • Multiple public and private blockchain solutions are supported

  • Deterministic behaviour for ID generation based on content, both on and off the blockchain. Id determination is fully blockchain agnostic

  • A concept of chains to store related data (entries)

  • Allow linking of data from entries within one chain to entries in another chain

3. Main concepts

3.1. Contexts

A context basically points to a public or private blockchain implementation. You can connect supported blockchains to the API using contexts. To get up to speed fast skip the contexts and use one of our provided contexts for testing (see below).
For now we support a single blockchain per context, but the API is created to support multiple blockchains in parallel in the future. If you have the need now to use multiple blockchains, simply use multiple contexts until support for multiple blockchains per context is implemented.

3.2. Chains

Chains allow you to store data (entries) that are related somehow within a single container. You can traverse data in a chain. Newer entries are stored at tha back of the chain. A chain is created by supplying it’s first entry

Example chain usage:

  • Store file hashes to prove existence or processing

  • Store information about a storage location (for instance Sharepoint List Item)

  • Store an audit trail

  • Store log entries

A chain is always created using a first entry. Actually this first entry makes up the chain information and Id (see later)

3.3. Entries

An entry is the main storage object. It has a single content part where you can store bytes. It also has zero or more metadata objects called external Id’s where you can store any byte data as well. You can see these external Ids as describing the content. There is no key-value support, so if you’d like to mimic that you have to make arangements for instance to make uneven external Id key, whilst even external Ids are value.

Please note that any information you store in an entry is visible for all participants of the particular blockchain network. If this is a public blockchain network, the whole world can read the information.

En entry has an ID that uniquely identifies this entry. It is based on 3 values.

  • The chain Id (see next section)

  • The content

  • The external Ids (metadata)

3.4. Registration Types

We provide default support for registering certain information types in external Ids. We recommend you use our Java based easy-blockchain-lib at https://github.com/Sphereon-Opensource/easy-blockchain-lib
Using a registration type, you can for instance store a document Id or Sharepoint List Item Id. You generate a registration for an external Id and place the value in the next external Id for the same entry.

This allows you to later lookup additional information from you application. Please note that the ID determination of entries and chains is deterministic, so any information you use during storage will need to be provided again during lookup, or you will have to traverse a chain to retrieve the information

We provide support to link from one Entry to another chain or entry. The latter entry does not have to reside in the same chain or even context whatsoever. Please note that the chain link support we provide includes the context name. If you change a context name, there is no support to change already stored chain links, since an important characteristic of a blockchain is it’s immutability.

A chainlink in our API is basically a mapping of our REST API to another chain or entry. Our easy-blockchain-lib at https://github.com/Sphereon-Opensource/easy-blockchain-lib provides support for links.

Use case with Sharepoint:
1) Store the hash of a file each time in a separate chain, using registration type HASH
2) Create separate chains for List Item Ids in sharepoint with registration type LIST_ITEM
3) Create a new entry in the file chain, with a chain link that points to the LIST_ITEM chain created above
4) Create a new entry in the List Item Id chain, with a chain link that points to the File Hash chain
5) Create separate chains for Lists with registration type LIST
6) Create chainlinks from the LIST chain to the List Item chain and vice versa
7) Create a separate chain for a Site with registration type SITE
8) Create chainlinks in an entry in the Site chain that points to the LIST chain and vice versa

The above allows you to lookup al kinds of important Sharepoint data based on the hash of file. So if you have an interface with Sharepoint you could determine at which list items a specific file has been. You can even do this with files outside of Sharepoint of course. If you’d also integrate a decission making process using the above mechanisme. You could check with merely a file the whole registration, audit and decision making process.

Please note that the we only provide creation and parsing of the links. Although the links map directly to the API structure, we leave resolving up to you.

4. Suported backends

Currently 3 different backends are supported of which we provide 2 context to directly start using the API. This means you can disregard the more complext context/backend API’s altogether.

4.1. Multichain

You can provide your own multichain nodes. All we need is access to the RPC server of a multichain node. We provide you with public nodes, by just using "multichain" as context (see public backends).
We use Multichain Streams to map the concept of Chains and Entries to supported data in multichain.

The benefits of multichain are that anchoring of data is done in a matter of seconds. It also allows for pretty large amounts of data as well as high throughput for a blockchain.

4.2. Factom

Factom is a blockchain dedicated to store data (facts) instead of merely value and transactions. Our API and the concepts of chains and entries are inspired by Factom.
Factom anchors it’s data in it’s own distributed ledger. A hash of the data gets anchored on the Bitcoin network every 10 minutes.

We provide a public context called "factom". Please note that any information is publicly available in the Factom blockchain!

4.3. Ethereum

Ethereum is a blockchain app platform with smart contract. We created such a smart contract that allows us to connect our API to Ethereum.
Please contact us if you have a need for Ethereum. We do not provide a context out of the box, because Ethereum is a bit expensive for the purpose of this API. Of course you are welcome to run your private Ethereum Ledger and use our contract and API.

4.4. Hyper Ledger Fabric

Support for Hyper Ledger is in testing right now and not available yet for the general public. Contact us for support.

4.5. Public contexts (backends)

We provide 2 public backends for now, using the contexts below:

1) multichain - Private Multichain blockchain, with fast anchoring
2) factom - Public Factom blockchain, with 10 minutes anchoring

We suggest you use the multichain context for testing and development. This context is a local multichain ledger we provide. It has quick anchor times. The contents you store here are only accessible using our API’s and are not publicly available. Please note that any data you store in the multichain context is available to other users using the same context!
The factom context is a public context. Any data you store here will end up in the public Factom blockchain and will be explorable from https://explorer.factom.org after waiting 10-15 minutes.

5. Id calculation

Ids are used to deterministically create or lookup chains and entries. This allows you to determine whether certain information already exists, or to store information in a particular chain you calculated. It also ideal for Proof of Existence type of scenario’s.

Example: Store the hash of a file in a specific chain with entry Id "File Hash Chain". This entry Id, will always resolve to the same chain Id. You use the hash of the file to create entries in this chain. All you have to do is determine the hash of the file and use that as an external Id in an entry. Now you can store the entry within the mentioned chain, or lookup whether the chain already has mentioned entry. If the latter is the case you will also get back the registration time(s) of the entry. This allows you to (dis)prove whether a certain file has been registered or not.

There are 3 ways to determine an Id of an entry or chain beforehand:

  • If you use Java as your programming language you can use the Operation class from our easy-blockchain-lib at https://github.com/Sphereon-Opensource/easy-blockchain-lib

  • Use our Id determination REST endpoints in this API. This means you will have to transfer information to determine the Id. If you do a lot Id calculation we recommend using one of the other aproaches

  • Calculate the Id yourself, using the pointers below. Please note that this involve some byte calculations. We suggest you use the code from the easy-blockchain-lib Operations class as a guide.

5.1. Chain Id calculation

As mentioned before. The first entry in the chain makes up the chain. Determining the chain Id therefore looks a lot like determining an entry Id.

A chain Id is calculated solely using data from the external Ids of the first entry. So there has to be at least one external Id in that entry. The content of the first entry is disregarded for the chain Id calculation. This allows you to store random information in the content of the entry, without it interfering with the Id calculation. This is handy for instance to store a Public key or some other information about the chain, which you cannot immediately supply again in the future.

1) Hash using SHA-256 all bytes from the external Ids individually and concatenate the result bytes of these hashes
2) Hash the resulting bytes again using SHA-256. This is the chain Id in bytes. We always communicate the chain Id in HEX format.
3) Convert the bytes chain Id to HEX

Java code example
   // import javax.xml.bind.DatatypeConverter;
   // import java.util.Arrays;

   public static String generateChainID(Entry entry) {
       EntryData entryData = entry.getEntryData();
       byte[] hash = new byte[0];

       for (ExternalId externalId : entryData.getExternalIds()) {
           hash = concat(hash, hashSHA256(externalId.getValue())); (1)
       }

       hash = hashSHA256(hash); (2)
       DatatypeConverter.printHexBinary(hash).toLowerCase(); (3)
   }

   // Concatenate two byte arrays
   public static byte[] concat(byte[] first, byte[] append) {
       byte[] result = Arrays.copyOf(first, first.length + append.length);
       System.arraycopy(append, 0, result, first.length, append.length);
       return result;
   }
  1. Concatenate the SHA-256 hash of the external Id values

  2. Hash the result again using SHA-256

  3. Convert chain Id byte array to hex (lowercase)

5.2. Entry Id calculation

Entry Id calculation is a lot like chain Id calculation. An entry is always linked to a chain, so the major difference is that you always have to include the chain Id in the calculation for the entry. You also include the content. The calculation is more complex however

1) Convert your entry (the content and external Ids) to a byte array
2) Hash using SHA-512 to previous entry bytes
3) concatenate the SHA-512 byte hash with the entry byte array from step 1
4) Hash using SHA-256 the value from step 3
5) Convert the byte array hash to hex

Java code example
   // import javax.xml.bind.DatatypeConverter;
   // import java.util.Arrays;


   public static String entryToHash(String chainIdHex, Entry entry) {
           // add entry bytes. That is the whole entryData as a byte array.
           // hash that with sha512, append the entrybytes to that 512 hash
           // hash that new byte array with sha256
           byte[] entryBytes = entryToBytes(chainIdHex, entry);
           byte[] hashed = hashSHA256(concat(hashSHA512(entryBytes), entryBytes));
           return DatatypeConverter.printHexBinary(hashed).toLowerCase();
   }


   protected static byte[] entryToBytes(String chainIdHex, Entry entry) {
           EntryData entryData = entry.getEntryData();
           byte[] chainID = null;

           // Check whether a chain Id is provided. Without it, this is a first entry that makes up a chain
           if (chainIdHex != null && !"".equals(chainIdHex)) {
               chainID = fromHex(chainIdHex); (1)
           } else {
               chainID = generateChainID(entryData); (2)
           }
           byte[] externalIds = externalIdsToBytes(entryData.getExternalIds());

           byte[] bytes = new byte[0];
           bytes = concat(bytes, (byte) 0);  (3)


           bytes = concat(bytes, chainID); (4)
           bytes = concat(bytes, externalIds); (5)
           if (entryData.getContent() != null) {
               bytes = concat(bytes, entryData.getContent()); (6)
           }
           return bytes;
    }


   protected static byte[] externalIdsToBytes(List<ExternalId> externalIds) {
           if (externalIds == null || externalIds.isEmpty()) {
               return new byte[]{(byte) 0};
           }
           byte[] bytes = new byte[0];
           short externalIdLength = 0;
           for (ExternalId externalId : externalIds) {
               if (externalId.getValue() == null) {
                   throw new RuntimeException("Empty External Id is not allowed");
               }
               // We need to add 2 bytes to store the next section's externalID length value
               externalIdLength += (externalId.getValue().length + 2); (7)
           }
           bytes = concat(bytes, toByteArray(externalIdLength)); (8)

           for (ExternalId externalId : externalIds) {
               bytes = concat(bytes, toByteArray(externalId.getValue().length)); (9)
               bytes = concat(bytes, externalId.getValue());
           }

           return bytes;
   }

   public static byte[] generateChainID(Entry entry) {
       // See previous section for implementation
   }

   public static byte[] fromHex(String hex) {
       return DatatypeConverter.parseHexBinary(hex);
   }

   // Concatenate two byte arrays
   public static byte[] concat(byte[] first, byte[] append) {
       byte[] result = Arrays.copyOf(first, first.length + append.length);
       System.arraycopy(append, 0, result, first.length, append.length);
       return result;
   }
  1. Hex chain Id is supplied. Convert it to bytes

  2. No chain Id supplied. This means it is the first entry of a chain. We now calculate a chain Id. See previous section.

  3. Add a version number for the algorithm (0 for now)

  4. Concatenate the chain Id (supplier or calculated)

  5. Concatenate the external Id bytes

  6. Concatenate the content bytes if there is a content value

  7. We create room for the length of all external Ids as well as 2 bytes to store the length for every individual external Id

  8. We supply a value in bytes for the room determined in the previous step

  9. Now we add the length of every individual external Id as well as the byte value

6. SDKs

Our API’s are based on the OpenAPI specification (formerly known as Swagger specification). This means you can pickup our REST API definition file and generate classes for your favorite programming language.

6.1. Provided SDKs and generated SDKs

6.1.1. Provide SDKs

For some popular programming languages we provide you with an SDK implementation at Github
https://github.com/Sphereon-SDK/easy-blockchain-sdk

6.1.2. Generate your own SDK

Please feel free to generate an SDK for your own programming language using our Swagger file. Please note that we do not officially support your SDK, but unofficially we are here to help of course.
You can use Swagger codegen for this (https://swagger.io/swagger-codegen). Swagger codegen support almost 100 programming languages.

Please use version 2.X of swagger codegen with our current API’s

6.2. Version compatibility between SDK and API

Al of our REST API’s follow the versioning scheme below

XX.YY

When the major number (XX) changes this means we completely redesign an API.
Minor number (YY) changes means smaller backwards comptible breaks within the API. An API can be changed forward compatible within the same minor number.

Our SDK follow the below versioning scheme

XX.YY.ZZ

The major (XX) and minor (YY) number always map directly to the accompanying REST API version.
The micro number (ZZ) is used if we add forward compatible changes to our REST API, or when bugs are encountered in a specific SDK.

7. Resources

7.1. All

All Blockchain APIs

7.1.1. Create a new backend

POST /backends
Description

Create a new backend. A Backend is the link to one blockchain implementation and it' s nodes. Unless you create your own private blockchain network, you should not have to create a new backend. Just use one of the public backends available.

Parameters
Type Name Description Schema

Body

backend
required

backend

Backend

Responses
HTTP Code Description Schema

202

Backend creation request received

Backend

400

Invalid backend request

ErrorResponse

401

Backend request not allowed

ErrorResponse

Consumes
  • application/json;charset=UTF-8

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
POST /blockchain/easy/0.10/backends HTTP/1.1
Authorization: Bearer example-a108-250e-804e-4ed13b543b30
Content-Type: application/json
Host: gw.api.cloud.sphereon.com
Content-Length: 779

{
  "apiVersion" : 1,
  "dataStructure" : "MULTICHAIN",
  "end" : "2020-12-24T02:04:35.192+02:00",
  "externalAccess" : {
    "blackList" : [ ],
    "modes" : [ "PUBLIC", "READ", "WRITE" ],
    "whiteList" : [ ]
  },
  "id" : "2f965a75-8c86-491b-9f17-06603883bfe8",
  "name" : "example-backend",
  "owner" : "example-owner",
  "rpcProviders" : [ {
    "access" : {
      "blackList" : [ ],
      "modes" : [ ],
      "whiteList" : [ ]
    },
    "host" : "http://localhost:8331",
    "id" : "3d2ce1a9-6ca3-478c-8b1b-2bbeb768b150",
    "ledgerName" : "example",
    "owner" : "example-owner",
    "ownerType" : "CUSTOMER",
    "password" : "password",
    "type" : "API",
    "username" : "username"
  } ],
  "start" : "2018-08-09T02:04:35.191+02:00"
}
Example HTTP response
HTTP/1.1 202 Accepted
Content-Type: application/json;charset=UTF-8
Content-Length: 608

{
  "apiVersion" : 1,
  "dataStructure" : "MULTICHAIN",
  "end" : "2020-12-24T00:04:35.192Z",
  "externalAccess" : {
    "blackList" : [ ],
    "modes" : [ "PUBLIC", "READ", "WRITE" ],
    "whiteList" : [ ]
  },
  "id" : "c947eb75-5afb-4ff0-a065-dc2c03cde9a0",
  "name" : "example-backend",
  "rpcProviders" : [ {
    "access" : {
      "blackList" : [ ],
      "modes" : [ ],
      "whiteList" : [ ]
    },
    "id" : "3d2ce1a9-6ca3-478c-8b1b-2bbeb768b150",
    "ledgerName" : "example",
    "ownerType" : "CUSTOMER",
    "type" : "API"
  } ],
  "start" : "2018-08-09T00:04:35.191Z"
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/blockchain/easy/0.10/backends' -i -X POST -H 'Authorization: Bearer example-a108-250e-804e-4ed13b543b30' -H 'Content-Type: application/json' -d '{
  "apiVersion" : 1,
  "dataStructure" : "MULTICHAIN",
  "end" : "2020-12-24T02:04:35.192+02:00",
  "externalAccess" : {
    "blackList" : [ ],
    "modes" : [ "PUBLIC", "READ", "WRITE" ],
    "whiteList" : [ ]
  },
  "id" : "2f965a75-8c86-491b-9f17-06603883bfe8",
  "name" : "example-backend",
  "owner" : "example-owner",
  "rpcProviders" : [ {
    "access" : {
      "blackList" : [ ],
      "modes" : [ ],
      "whiteList" : [ ]
    },
    "host" : "http://localhost:8331",
    "id" : "3d2ce1a9-6ca3-478c-8b1b-2bbeb768b150",
    "ledgerName" : "example",
    "owner" : "example-owner",
    "ownerType" : "CUSTOMER",
    "password" : "password",
    "type" : "API",
    "username" : "username"
  } ],
  "start" : "2018-08-09T02:04:35.191+02:00"
}'

7.1.2. List backends

GET /backends
Description

List existing backends. Optionally including public backends of others. Please note that we never return sensitive information like password or rpc hosts. Even not for backend owners themselves

Parameters
Type Name Description Schema Default

Query

includePublic
optional

includePublic

boolean

"false"

Responses
HTTP Code Description Schema

200

List of backend

< Backend > array

400

Invalid backend request

ErrorResponse

401

Backend request not allowed

ErrorResponse

404

Backend not found

ErrorResponse

Consumes
  • application/json

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
GET /blockchain/easy/0.10/backends?includePublic=true HTTP/1.1
Authorization: Bearer example-a108-250e-804e-4ed13b543b30
Content-Type: application/json
Host: gw.api.cloud.sphereon.com
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1906

[ {
  "apiVersion" : 1,
  "dataStructure" : "MULTICHAIN",
  "end" : "2020-12-24T00:04:35.192Z",
  "externalAccess" : {
    "blackList" : [ ],
    "modes" : [ "PUBLIC", "READ", "WRITE" ],
    "whiteList" : [ ]
  },
  "id" : "c947eb75-5afb-4ff0-a065-dc2c03cde9a0",
  "name" : "example-backend",
  "rpcProviders" : [ {
    "access" : {
      "blackList" : [ ],
      "modes" : [ ],
      "whiteList" : [ ]
    },
    "id" : "3d2ce1a9-6ca3-478c-8b1b-2bbeb768b150",
    "ledgerName" : "example",
    "ownerType" : "CUSTOMER",
    "type" : "API"
  } ],
  "start" : "2018-08-09T00:04:35.191Z"
}, {
  "apiVersion" : 1,
  "dataStructure" : "MULTICHAIN",
  "end" : null,
  "externalAccess" : {
    "blackList" : [ ],
    "modes" : [ "READ", "WRITE", "PUBLIC" ],
    "whiteList" : [ ]
  },
  "id" : "multichain",
  "name" : "multichain",
  "rpcProviders" : [ {
    "access" : {
      "blackList" : [ ],
      "modes" : [ ],
      "whiteList" : [ ]
    },
    "id" : "9f5c7835-40b3-48a8-99d8-7429b43bab99",
    "ledgerName" : "testchain",
    "ownerType" : "PROVIDER",
    "type" : "API"
  } ],
  "start" : null
}, {
  "apiVersion" : 1,
  "dataStructure" : "FACTOM",
  "end" : null,
  "externalAccess" : {
    "blackList" : [ ],
    "modes" : [ "READ", "WRITE", "PUBLIC" ],
    "whiteList" : [ ]
  },
  "id" : "factom",
  "name" : "factom",
  "rpcProviders" : [ {
    "access" : {
      "blackList" : [ ],
      "modes" : [ ],
      "whiteList" : [ ]
    },
    "id" : "b4182bd7-3d95-402d-b0b1-7faf1a14de67",
    "ledgerName" : null,
    "ownerType" : "PROVIDER",
    "type" : "API"
  }, {
    "access" : {
      "blackList" : [ ],
      "modes" : [ ],
      "whiteList" : [ ]
    },
    "id" : "6b94ef11-4aa4-495a-aa05-28feb5e213b1",
    "ledgerName" : null,
    "ownerType" : "PROVIDER",
    "type" : "WALLET"
  } ],
  "start" : null
} ]
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/blockchain/easy/0.10/backends?includePublic=true' -i -H 'Authorization: Bearer example-a108-250e-804e-4ed13b543b30' -H 'Content-Type: application/json'

7.1.3. Get backend by id

GET /backends/{backendId}
Description

Get existing backend by id (not by name). Optionally including public backend of others. Please note that we never return sensitive information like password or rpc hosts. Even not for backend owners themselves

Parameters
Type Name Description Schema Default

Path

backendId
required

backendId

string

Query

includePublic
optional

includePublic

boolean

"false"

Responses
HTTP Code Description Schema

200

Backend

Backend

400

Invalid backend request

ErrorResponse

401

Backend request not allowed

ErrorResponse

404

Backend not found

ErrorResponse

Consumes
  • application/json

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
GET /blockchain/easy/0.10/backends/c947eb75-5afb-4ff0-a065-dc2c03cde9a0 HTTP/1.1
Authorization: Bearer example-a108-250e-804e-4ed13b543b30
Content-Type: application/json
Host: gw.api.cloud.sphereon.com
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 608

{
  "apiVersion" : 1,
  "dataStructure" : "MULTICHAIN",
  "end" : "2020-12-24T00:04:35.192Z",
  "externalAccess" : {
    "blackList" : [ ],
    "modes" : [ "PUBLIC", "READ", "WRITE" ],
    "whiteList" : [ ]
  },
  "id" : "c947eb75-5afb-4ff0-a065-dc2c03cde9a0",
  "name" : "example-backend",
  "rpcProviders" : [ {
    "access" : {
      "blackList" : [ ],
      "modes" : [ ],
      "whiteList" : [ ]
    },
    "id" : "3d2ce1a9-6ca3-478c-8b1b-2bbeb768b150",
    "ledgerName" : "example",
    "ownerType" : "CUSTOMER",
    "type" : "API"
  } ],
  "start" : "2018-08-09T00:04:35.191Z"
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/blockchain/easy/0.10/backends/c947eb75-5afb-4ff0-a065-dc2c03cde9a0' -i -H 'Authorization: Bearer example-a108-250e-804e-4ed13b543b30' -H 'Content-Type: application/json'

7.1.4. Delete a backend

DELETE /backends/{backendId}
Description

Delete backend by id (not by name)

Parameters
Type Name Description Schema

Path

backendId
required

backendId

string

Responses
HTTP Code Description Schema

200

Backend deleted

Backend

400

Invalid backend request

ErrorResponse

401

Backend request not allowed

ErrorResponse

404

Backend not found

ErrorResponse

Consumes
  • application/json

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
DELETE /blockchain/easy/0.10/backends/c947eb75-5afb-4ff0-a065-dc2c03cde9a0 HTTP/1.1
Authorization: Bearer example-a108-250e-804e-4ed13b543b30
Content-Type: application/json
Host: gw.api.cloud.sphereon.com
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 608

{
  "apiVersion" : 1,
  "dataStructure" : "MULTICHAIN",
  "end" : "2020-12-24T00:04:35.192Z",
  "externalAccess" : {
    "blackList" : [ ],
    "modes" : [ "PUBLIC", "READ", "WRITE" ],
    "whiteList" : [ ]
  },
  "id" : "c947eb75-5afb-4ff0-a065-dc2c03cde9a0",
  "name" : "example-backend",
  "rpcProviders" : [ {
    "access" : {
      "blackList" : [ ],
      "modes" : [ ],
      "whiteList" : [ ]
    },
    "id" : "3d2ce1a9-6ca3-478c-8b1b-2bbeb768b150",
    "ledgerName" : "example",
    "ownerType" : "CUSTOMER",
    "type" : "API"
  } ],
  "start" : "2018-08-09T00:04:35.191Z"
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/blockchain/easy/0.10/backends/c947eb75-5afb-4ff0-a065-dc2c03cde9a0' -i -X DELETE -H 'Authorization: Bearer example-a108-250e-804e-4ed13b543b30' -H 'Content-Type: application/json'

7.1.5. Find backends

GET /backends/{backendId}/find
Description

Find existing backend(s) by id (single result) and/or name (multiple results). Optionally including public backends of others. Please note that we never return sensitive information like password or rpc hosts. Even not for backend owners themselves

Parameters
Type Name Description Schema Default

Path

backendId
required

backendId

string

Query

includePublic
optional

includePublic

boolean

"false"

Responses
HTTP Code Description Schema

200

List of backend

< Backend > array

400

Invalid backend request

ErrorResponse

401

Backend request not allowed

ErrorResponse

404

Backend not found

ErrorResponse

Consumes
  • application/json

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
GET /blockchain/easy/0.10/backends/c947eb75-5afb-4ff0-a065-dc2c03cde9a0/find HTTP/1.1
Authorization: Bearer example-a108-250e-804e-4ed13b543b30
Content-Type: application/json
Host: gw.api.cloud.sphereon.com
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 612

[ {
  "apiVersion" : 1,
  "dataStructure" : "MULTICHAIN",
  "end" : "2020-12-24T00:04:35.192Z",
  "externalAccess" : {
    "blackList" : [ ],
    "modes" : [ "PUBLIC", "READ", "WRITE" ],
    "whiteList" : [ ]
  },
  "id" : "c947eb75-5afb-4ff0-a065-dc2c03cde9a0",
  "name" : "example-backend",
  "rpcProviders" : [ {
    "access" : {
      "blackList" : [ ],
      "modes" : [ ],
      "whiteList" : [ ]
    },
    "id" : "3d2ce1a9-6ca3-478c-8b1b-2bbeb768b150",
    "ledgerName" : "example",
    "ownerType" : "CUSTOMER",
    "type" : "API"
  } ],
  "start" : "2018-08-09T00:04:35.191Z"
} ]
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/blockchain/easy/0.10/backends/c947eb75-5afb-4ff0-a065-dc2c03cde9a0/find' -i -H 'Authorization: Bearer example-a108-250e-804e-4ed13b543b30' -H 'Content-Type: application/json'

7.1.6. Create context

POST /contexts
Description

Create a new context

Parameters
Type Name Description Schema

Body

context
required

context

Context

Responses
HTTP Code Description Schema

200

Context already exists

Context

202

Context creation request received

Context

400

Invalid context request

ErrorResponse

401

Backend request not allowed

ErrorResponse

Consumes
  • application/json;charset=UTF-8

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
POST /blockchain/easy/0.10/contexts HTTP/1.1
Authorization: Bearer example-a108-250e-804e-4ed13b543b30
Content-Type: application/json
Host: gw.api.cloud.sphereon.com
Content-Length: 225

{
  "access" : {
    "blackList" : [ ],
    "modes" : [ "READ", "WRITE" ],
    "whiteList" : [ ]
  },
  "backendIds" : [ "c947eb75-5afb-4ff0-a065-dc2c03cde9a0" ],
  "name" : "testchain",
  "owner" : "context-owner"
}
Example HTTP response
HTTP/1.1 202 Accepted
Content-Type: application/json;charset=UTF-8
Content-Length: 245

{
  "access" : {
    "blackList" : [ ],
    "modes" : [ "READ", "WRITE" ],
    "whiteList" : [ ]
  },
  "backendIds" : [ "c947eb75-5afb-4ff0-a065-dc2c03cde9a0" ],
  "id" : "8e0e9c9f-408b-406f-ae93-c42e7cc9fb79",
  "name" : "testchain"
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/blockchain/easy/0.10/contexts' -i -X POST -H 'Authorization: Bearer example-a108-250e-804e-4ed13b543b30' -H 'Content-Type: application/json' -d '{
  "access" : {
    "blackList" : [ ],
    "modes" : [ "READ", "WRITE" ],
    "whiteList" : [ ]
  },
  "backendIds" : [ "c947eb75-5afb-4ff0-a065-dc2c03cde9a0" ],
  "name" : "testchain",
  "owner" : "context-owner"
}'

7.1.7. Get context

GET /contexts/{context}
Description

Get an existing context

Parameters
Type Name Description Schema

Path

context
required

context

string

Responses
HTTP Code Description Schema

200

Context

Context

400

Invalid context request

ErrorResponse

404

Context not found

ErrorResponse

Consumes
  • application/json

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
GET /blockchain/easy/0.10/contexts/factom?includePublic=true HTTP/1.1
Authorization: Bearer example-a108-250e-804e-4ed13b543b30
Content-Type: application/json
Host: gw.api.cloud.sphereon.com
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 222

{
  "access" : {
    "blackList" : [ ],
    "modes" : [ "READ", "WRITE", "PUBLIC" ],
    "whiteList" : [ ]
  },
  "backendIds" : [ "factom" ],
  "id" : "22fe22f8-020f-459f-bdeb-0f49b8317445",
  "name" : "factom"
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/blockchain/easy/0.10/contexts/factom?includePublic=true' -i -H 'Authorization: Bearer example-a108-250e-804e-4ed13b543b30' -H 'Content-Type: application/json'

7.1.8. Delete context

DELETE /contexts/{context}
Description

Delete an existing context

Parameters
Type Name Description Schema

Path

context
required

context

string

Responses
HTTP Code Description Schema

200

The deleted context

Context

400

Invalid context request

ErrorResponse

404

Context not found

ErrorResponse

Consumes
  • application/json

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
DELETE /blockchain/easy/0.10/contexts/testchain HTTP/1.1
Authorization: Bearer example-a108-250e-804e-4ed13b543b30
Content-Type: application/json
Host: gw.api.cloud.sphereon.com
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 245

{
  "access" : {
    "blackList" : [ ],
    "modes" : [ "READ", "WRITE" ],
    "whiteList" : [ ]
  },
  "backendIds" : [ "c947eb75-5afb-4ff0-a065-dc2c03cde9a0" ],
  "id" : "8e0e9c9f-408b-406f-ae93-c42e7cc9fb79",
  "name" : "testchain"
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/blockchain/easy/0.10/contexts/testchain' -i -X DELETE -H 'Authorization: Bearer example-a108-250e-804e-4ed13b543b30' -H 'Content-Type: application/json'

7.1.9. Create a new chain

POST /{context}/chains
Description

Create a new chain. Create a new chain. You can regard a chain as a blockchain within a blockchain, All entries in a chain are linked and relies on data from previous entries in the chain.

Parameters
Type Name Description Schema

Path

context
required

context

string

Body

chain
required

Create a chain using the first entry supplied. The entry needs at least a (combination of) globaly unique external Id in the complete Blockchain network!

Chain

Responses
HTTP Code Description Schema

200

Chain already exists

CommittedChainResponse

202

Chain creation request received

CommittedChainResponse

400

Invalid blockchain request

ErrorResponse

Consumes
  • application/json;charset=UTF-8

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
POST /blockchain/easy/0.10/testchain/chains HTTP/1.1
Authorization: Bearer example-a108-250e-804e-4ed13b543b30
Content-Type: application/json
Host: gw.api.cloud.sphereon.com
Content-Length: 278

{
  "firstEntry" : {
    "entryData" : {
      "content" : "MXN0IEVudHJ5IENvbnRlbnQgKENoYWluKQ==",
      "externalIds" : [ {
        "value" : "MXN0IGV4dGVybmFsIGlkIEAgMTUzNDIwNTA3NTE5Mg=="
      }, {
        "value" : "MXN0IGV4dGVybmFsIGlkIDI="
      } ]
    }
  }
}
Example HTTP response
HTTP/1.1 202 Accepted
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache
Expires: 0
Content-Type: application/json;charset=UTF-8
Content-Length: 553

{
  "chain" : {
    "chain" : {
      "firstEntry" : {
        "entryData" : {
          "content" : "MXN0IEVudHJ5IENvbnRlbnQgKENoYWluKQ==",
          "externalIds" : [ {
            "value" : "MXN0IGV4dGVybmFsIGlkIEAgMTUzNDIwNTA3NTE5Mg=="
          }, {
            "value" : "MXN0IGV4dGVybmFsIGlkIDI="
          } ]
        }
      }
    },
    "id" : "1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79"
  },
  "commitTime" : "2018-08-14T02:04:35.946+02:00",
  "creationRequestTime" : "2018-08-14T02:04:35.943+02:00"
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/blockchain/easy/0.10/testchain/chains' -i -X POST -H 'Authorization: Bearer example-a108-250e-804e-4ed13b543b30' -H 'Content-Type: application/json' -d '{
  "firstEntry" : {
    "entryData" : {
      "content" : "MXN0IEVudHJ5IENvbnRlbnQgKENoYWluKQ==",
      "externalIds" : [ {
        "value" : "MXN0IGV4dGVybmFsIGlkIEAgMTUzNDIwNTA3NTE5Mg=="
      }, {
        "value" : "MXN0IGV4dGVybmFsIGlkIDI="
      } ]
    }
  }
}'

7.1.10. Predetermine id of chain

POST /{context}/chains/id
Description

Pre determine the Id of a chain without anchoring it in the blockchain. You determine the Id that the chain would receive once it would have been anchored

Parameters
Type Name Description Schema Default

Path

context
required

context

string

Query

checkExistence
optional

Check whether the id exists

boolean

"false"

Body

chain
required

Determine a chain hash. The entry needs at least a (combination of) globally unique external Id in the complete Blockchain network!

Chain

Responses
HTTP Code Description Schema

200

Chain request received and hash calculated

IdResponse

400

Invalid blockchain request

ErrorResponse

Consumes
  • application/json;charset=UTF-8

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
POST /blockchain/easy/0.10/testchain/chains/id?checkExistence=true HTTP/1.1
Authorization: Bearer example-a108-250e-804e-4ed13b543b30
Content-Type: application/json
Host: gw.api.cloud.sphereon.com
Content-Length: 278

{
  "firstEntry" : {
    "entryData" : {
      "content" : "MXN0IEVudHJ5IENvbnRlbnQgKENoYWluKQ==",
      "externalIds" : [ {
        "value" : "MXN0IGV4dGVybmFsIGlkIEAgMTUzNDIwNTA3NTE5Mg=="
      }, {
        "value" : "MXN0IGV4dGVybmFsIGlkIDI="
      } ]
    }
  }
}
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 103

{
  "Id" : "1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79",
  "exists" : "True"
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/blockchain/easy/0.10/testchain/chains/id?checkExistence=true' -i -X POST -H 'Authorization: Bearer example-a108-250e-804e-4ed13b543b30' -H 'Content-Type: application/json' -d '{
  "firstEntry" : {
    "entryData" : {
      "content" : "MXN0IEVudHJ5IENvbnRlbnQgKENoYWluKQ==",
      "externalIds" : [ {
        "value" : "MXN0IGV4dGVybmFsIGlkIEAgMTUzNDIwNTA3NTE5Mg=="
      }, {
        "value" : "MXN0IGV4dGVybmFsIGlkIDI="
      } ]
    }
  }
}'

7.1.11. Determine chain id exists

GET /{context}/chains/id/{chainId}
Description

Determine whether the Id of a chain exists in the blockchain

Parameters
Type Name Description Schema

Path

chainId
required

chainId

string

Path

context
required

context

string

Responses
HTTP Code Description Schema

200

Chain existence

IdResponse

400

Invalid blockchain request

ErrorResponse

Consumes
  • application/json

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
GET /blockchain/easy/0.10/testchain/chains/id/1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79 HTTP/1.1
Authorization: Bearer example-a108-250e-804e-4ed13b543b30
Content-Type: application/json
Host: gw.api.cloud.sphereon.com
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 103

{
  "Id" : "1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79",
  "exists" : "True"
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/blockchain/easy/0.10/testchain/chains/id/1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79' -i -H 'Authorization: Bearer example-a108-250e-804e-4ed13b543b30' -H 'Content-Type: application/json'

7.1.12. Predetermine id of an entry

POST /{context}/chains/id/{chainId}/entries
Description

Pre determine the Id of an entry request without anchoring the entry

Parameters
Type Name Description Schema Default

Path

chainId
required

chainId

string

Path

context
required

context

string

Query

checkExistence
optional

Check whether the id exists

boolean

"false"

Body

entry
required

The entry to determine the hash for on the specified chain

Entry

Responses
HTTP Code Description Schema

200

Entry request received and hash calculated

IdResponse

400

Invalid entry request

ErrorResponse

404

Invalid chain id. Only possible when existence is checked

ErrorResponse

Consumes
  • application/json;charset=UTF-8

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

7.1.13. Determine entry id exists

GET /{context}/chains/id/{chainId}/entries/{entryId}
Description

Determine whether the Id of an entry exists in the blockchain

Parameters
Type Name Description Schema

Path

chainId
required

chainId

string

Path

context
required

context

string

Path

entryId
required

entryId

string

Responses
HTTP Code Description Schema

200

Entry existence

IdResponse

400

Invalid blockchain request

ErrorResponse

404

Invalid chain id

ErrorResponse

Consumes
  • application/json

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

7.1.14. Create a new entry in the provided chain

POST /{context}/chains/{chainId}/entries
Description

Create a new entry in the provided chain. The entry will be linked to the previous entry. If the entry already exists, the API will add an anchor time, since the entry Id would be the same as the previously registered entry

Parameters
Type Name Description Schema

Path

chainId
required

chainId

string

Path

context
required

context

string

Query

currentAnchorTime
optional

string (date-time)

Body

entry
required

Create a new entry for the specified chain

Entry

Responses
HTTP Code Description Schema

200

Entry already exists

CommittedEntryResponse

202

Entry creation request received

CommittedEntryResponse

400

Invalid entry request

ErrorResponse

404

Chain does not exist (yet)

ErrorResponse

Consumes
  • application/json;charset=UTF-8

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
POST /blockchain/easy/0.10/testchain/chains/1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79/entries HTTP/1.1
Authorization: Bearer example-a108-250e-804e-4ed13b543b30
Content-Type: application/json
Host: gw.api.cloud.sphereon.com
Content-Length: 221

{
  "entryData" : {
    "content" : "M3JkIEVudHJ5IENvbnRlbnQ=",
    "externalIds" : [ {
      "value" : "M3JkIGVudHJ5IGV4dGVybmFsIGlkIDE="
    }, {
      "value" : "M3JkIGVudHJ5IGV4dGVybmFsIGlkIDI="
    } ]
  }
}
Example HTTP response
HTTP/1.1 202 Accepted
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache
Expires: 0
Content-Type: application/json;charset=UTF-8
Content-Length: 613

{
  "commitTime" : "2018-08-14T02:04:36.355+02:00",
  "creationRequestTime" : "2018-08-14T02:04:36.355+02:00",
  "entry" : {
    "chainId" : "1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79",
    "entry" : {
      "entryData" : {
        "content" : "M3JkIEVudHJ5IENvbnRlbnQ=",
        "externalIds" : [ {
          "value" : "M3JkIGVudHJ5IGV4dGVybmFsIGlkIDE="
        }, {
          "value" : "M3JkIGVudHJ5IGV4dGVybmFsIGlkIDI="
        } ]
      }
    },
    "entryId" : "9aec611c2f7b309b3171d61eb54ad8052c2a80c7a5ef9804544cc2ce84e3d094",
    "rawBackendStructure" : null
  }
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/blockchain/easy/0.10/testchain/chains/1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79/entries' -i -X POST -H 'Authorization: Bearer example-a108-250e-804e-4ed13b543b30' -H 'Content-Type: application/json' -d '{
  "entryData" : {
    "content" : "M3JkIEVudHJ5IENvbnRlbnQ=",
    "externalIds" : [ {
      "value" : "M3JkIGVudHJ5IGV4dGVybmFsIGlkIDE="
    }, {
      "value" : "M3JkIGVudHJ5IGV4dGVybmFsIGlkIDI="
    } ]
  }
}'

7.1.15. Get an existing entry in the provided chain

POST /{context}/chains/{chainId}/entries/entry
Description

Get an existing entry in the provided chain

Parameters
Type Name Description Schema

Path

chainId
required

chainId

string

Path

context
required

context

string

Query

currentAnchorTime
optional

string (date-time)

Body

entry
required

Retrieve the entry

Entry

Responses
HTTP Code Description Schema

200

The existing request entry

AnchoredEntryResponse

400

Invalid chain id

ErrorResponse

404

Request entry does not exists

AnchoredEntryResponse

Consumes
  • application/json

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

7.1.16. Get the entry after the supplied entry Id (the next) in the provided chain

POST /{context}/chains/{chainId}/entries/entry/next
Description

Get the entry after the supplied entry Id (the next) in the provided chain

Parameters
Type Name Description Schema

Path

chainId
required

chainId

string

Path

context
required

context

string

Query

currentAnchorTime
optional

string (date-time)

Body

entry
required

Retrieve the entry

Entry

Responses
HTTP Code Description Schema

200

The existing next entry

AnchoredEntryResponse

400

Invalid chain id

ErrorResponse

404

Request entry does not exists

AnchoredEntryResponse

Consumes
  • application/json

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

7.1.17. Get the entry before the supplied entry Id (the previous) in the provided chain

POST /{context}/chains/{chainId}/entries/entry/previous
Description

Get the entry before the supplied entry Id (the previous) in the provided chain

Parameters
Type Name Description Schema

Path

chainId
required

chainId

string

Path

context
required

context

string

Query

currentAnchorTime
optional

string (date-time)

Body

entry
required

Retrieve the entry

Entry

Responses
HTTP Code Description Schema

200

The existing previous entry

AnchoredEntryResponse

400

Invalid chain id

ErrorResponse

404

Request entry does not exists

AnchoredEntryResponse

Consumes
  • application/json

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

7.1.18. Get the first entry in the provided chain

GET /{context}/chains/{chainId}/entries/first
Description

Get the first entry in the provided chain. This is the oldest entry also called the chain tail. Please note that the achorTimes will only contain the first anchor time. Call getEntry to retrieve all times

Parameters
Type Name Description Schema

Path

chainId
required

chainId

string

Path

context
required

context

string

Responses
HTTP Code Description Schema

200

The existing anchored first entry

AnchoredEntryResponse

400

Invalid chain id

ErrorResponse

404

Entry does not exists

ErrorResponse

Consumes
  • application/json

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
GET /blockchain/easy/0.10/testchain/chains/1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79/entries/first HTTP/1.1
Authorization: Bearer example-a108-250e-804e-4ed13b543b30
Content-Type: application/json
Host: gw.api.cloud.sphereon.com
Example HTTP response
HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache
Expires: 0
Content-Type: application/json;charset=UTF-8
Content-Length: 1809

{
  "anchorState" : "ANCHORED",
  "anchorTimes" : [ "2018-08-14T02:04:52+02:00" ],
  "anchoredEntry" : {
    "chainId" : "1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79",
    "entry" : {
      "entryData" : {
        "content" : "MXN0IEVudHJ5IENvbnRlbnQgKENoYWluKQ==",
        "externalIds" : [ {
          "value" : "MXN0IGV4dGVybmFsIGlkIEAgMTUzNDIwNTA3NTE5Mg=="
        }, {
          "value" : "MXN0IGV4dGVybmFsIGlkIDI="
        } ]
      }
    },
    "entryId" : "afcc331d5325111e7ee478f2dfd506b9a7b009784e3866adac2d579edbd05063",
    "rawBackendStructure" : "{\r\n  \"error\" : null,\r\n  \"id\" : 14,\r\n  \"result\" : {\r\n    \"blockhash\" : \"00c61e9364fe84b7fa727b79e7c5a8106ff8b5e3e327f88acb840ec45f4e5ae4\",\r\n    \"blockindex\" : 2,\r\n    \"blocktime\" : 1534205092,\r\n    \"confirmations\" : 2,\r\n    \"data\" : \"7b0d0a202022636f6e74656e7422203a20224d584e304945567564484a3549454e76626e526c626e51674b454e6f59576c754b513d3d222c0d0a20202265787465726e616c49647322203a205b207b0d0a202020202276616c756522203a20224d584e304947563464475679626d467349476c6b494541674d54557a4e4449774e5441334e5445354d673d3d220d0a20207d2c207b0d0a202020202276616c756522203a20224d584e304947563464475679626d467349476c6b4944493d220d0a20207d205d0d0a7d\",\r\n    \"key\" : \"afcc331d5325111e7ee478f2dfd506b9a7b009784e3866adac2d579edbd05063\",\r\n    \"publishers\" : [ \"1Lj7C69vHBzDvyDx8NPrEYo7iwcDNHvnb1joYY\" ],\r\n    \"time\" : 1534205076,\r\n    \"timereceived\" : 1534205076,\r\n    \"txid\" : \"bd1592557da0026bc7f11b2e2ccb50a27feaf98d3febced7bc2ef2712c419ef1\",\r\n    \"valid\" : true,\r\n    \"vout\" : 0\r\n  }\r\n}"
  },
  "currentAnchorTime" : "2018-08-14T02:04:52+02:00",
  "firstAnchorTime" : "2018-08-14T02:04:52+02:00",
  "lastAnchorTime" : "2018-08-14T02:04:52+02:00"
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/blockchain/easy/0.10/testchain/chains/1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79/entries/first' -i -H 'Authorization: Bearer example-a108-250e-804e-4ed13b543b30' -H 'Content-Type: application/json'

7.1.19. Get the last entry in the provided chain.

GET /{context}/chains/{chainId}/entries/last
Description

Get the last entry in the provided chain. This is the most recent entry also called the chain head. Please note that the achorTimes will only contain the latest anchor time. Call getEntry to retrieve all times

Parameters
Type Name Description Schema

Path

chainId
required

chainId

string

Path

context
required

context

string

Responses
HTTP Code Description Schema

200

The existing anchored entry

AnchoredEntryResponse

400

Invalid chain id

ErrorResponse

404

Entry does not exists

ErrorResponse

Consumes
  • application/json

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
GET /blockchain/easy/0.10/testchain/chains/1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79/entries/last HTTP/1.1
Authorization: Bearer example-a108-250e-804e-4ed13b543b30
Content-Type: application/json
Host: gw.api.cloud.sphereon.com
Example HTTP response
HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache
Expires: 0
Content-Type: application/json;charset=UTF-8
Content-Length: 1761

{
  "anchorState" : "ANCHORED",
  "anchorTimes" : [ "2018-08-14T02:04:52+02:00" ],
  "anchoredEntry" : {
    "chainId" : "1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79",
    "entry" : {
      "entryData" : {
        "content" : "M3JkIEVudHJ5IENvbnRlbnQ=",
        "externalIds" : [ {
          "value" : "M3JkIGVudHJ5IGV4dGVybmFsIGlkIDE="
        }, {
          "value" : "M3JkIGVudHJ5IGV4dGVybmFsIGlkIDI="
        } ]
      }
    },
    "entryId" : "9aec611c2f7b309b3171d61eb54ad8052c2a80c7a5ef9804544cc2ce84e3d094",
    "rawBackendStructure" : "{\r\n  \"error\" : null,\r\n  \"id\" : 12,\r\n  \"result\" : {\r\n    \"blockhash\" : \"00c61e9364fe84b7fa727b79e7c5a8106ff8b5e3e327f88acb840ec45f4e5ae4\",\r\n    \"blockindex\" : 4,\r\n    \"blocktime\" : 1534205092,\r\n    \"confirmations\" : 2,\r\n    \"data\" : \"7b0d0a202022636f6e74656e7422203a20224d334a6b4945567564484a3549454e76626e526c626e513d222c0d0a20202265787465726e616c49647322203a205b207b0d0a202020202276616c756522203a20224d334a6b4947567564484a354947563464475679626d467349476c6b4944453d220d0a20207d2c207b0d0a202020202276616c756522203a20224d334a6b4947567564484a354947563464475679626d467349476c6b4944493d220d0a20207d205d0d0a7d\",\r\n    \"key\" : \"9aec611c2f7b309b3171d61eb54ad8052c2a80c7a5ef9804544cc2ce84e3d094\",\r\n    \"publishers\" : [ \"1Lj7C69vHBzDvyDx8NPrEYo7iwcDNHvnb1joYY\" ],\r\n    \"time\" : 1534205076,\r\n    \"timereceived\" : 1534205076,\r\n    \"txid\" : \"9e9a8c956fff10790ed0befd145b93b65297bc2428dfa8dae3833d72c2a18f25\",\r\n    \"valid\" : true,\r\n    \"vout\" : 0\r\n  }\r\n}"
  },
  "currentAnchorTime" : "2018-08-14T02:04:52+02:00",
  "firstAnchorTime" : "2018-08-14T02:04:52+02:00",
  "lastAnchorTime" : "2018-08-14T02:04:52+02:00"
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/blockchain/easy/0.10/testchain/chains/1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79/entries/last' -i -H 'Authorization: Bearer example-a108-250e-804e-4ed13b543b30' -H 'Content-Type: application/json'

7.1.20. Get an existing entry in the provided chain

GET /{context}/chains/{chainId}/entries/{entryId}
Description

Get an existing entry in the provided chain

Parameters
Type Name Description Schema

Path

chainId
required

chainId

string

Path

context
required

context

string

Path

entryId
required

entryId

string

Query

currentAnchorTime
optional

string (date-time)

Responses
HTTP Code Description Schema

200

The existing entry

AnchoredEntryResponse

400

Invalid chain id

ErrorResponse

404

Entry does not exists

ErrorResponse

Consumes
  • application/json

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
GET /blockchain/easy/0.10/testchain/chains/1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79/entries/9aec611c2f7b309b3171d61eb54ad8052c2a80c7a5ef9804544cc2ce84e3d094 HTTP/1.1
Authorization: Bearer example-a108-250e-804e-4ed13b543b30
Content-Type: application/json
Host: gw.api.cloud.sphereon.com
Example HTTP response
HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache
Expires: 0
Content-Type: application/json;charset=UTF-8
Content-Length: 1761

{
  "anchorState" : "ANCHORED",
  "anchorTimes" : [ "2018-08-14T02:04:52+02:00" ],
  "anchoredEntry" : {
    "chainId" : "1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79",
    "entry" : {
      "entryData" : {
        "content" : "M3JkIEVudHJ5IENvbnRlbnQ=",
        "externalIds" : [ {
          "value" : "M3JkIGVudHJ5IGV4dGVybmFsIGlkIDE="
        }, {
          "value" : "M3JkIGVudHJ5IGV4dGVybmFsIGlkIDI="
        } ]
      }
    },
    "entryId" : "9aec611c2f7b309b3171d61eb54ad8052c2a80c7a5ef9804544cc2ce84e3d094",
    "rawBackendStructure" : "{\r\n  \"error\" : null,\r\n  \"id\" : 10,\r\n  \"result\" : {\r\n    \"blockhash\" : \"00c61e9364fe84b7fa727b79e7c5a8106ff8b5e3e327f88acb840ec45f4e5ae4\",\r\n    \"blockindex\" : 4,\r\n    \"blocktime\" : 1534205092,\r\n    \"confirmations\" : 2,\r\n    \"data\" : \"7b0d0a202022636f6e74656e7422203a20224d334a6b4945567564484a3549454e76626e526c626e513d222c0d0a20202265787465726e616c49647322203a205b207b0d0a202020202276616c756522203a20224d334a6b4947567564484a354947563464475679626d467349476c6b4944453d220d0a20207d2c207b0d0a202020202276616c756522203a20224d334a6b4947567564484a354947563464475679626d467349476c6b4944493d220d0a20207d205d0d0a7d\",\r\n    \"key\" : \"9aec611c2f7b309b3171d61eb54ad8052c2a80c7a5ef9804544cc2ce84e3d094\",\r\n    \"publishers\" : [ \"1Lj7C69vHBzDvyDx8NPrEYo7iwcDNHvnb1joYY\" ],\r\n    \"time\" : 1534205076,\r\n    \"timereceived\" : 1534205076,\r\n    \"txid\" : \"9e9a8c956fff10790ed0befd145b93b65297bc2428dfa8dae3833d72c2a18f25\",\r\n    \"valid\" : true,\r\n    \"vout\" : 0\r\n  }\r\n}"
  },
  "currentAnchorTime" : "2018-08-14T02:04:52+02:00",
  "firstAnchorTime" : "2018-08-14T02:04:52+02:00",
  "lastAnchorTime" : "2018-08-14T02:04:52+02:00"
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/blockchain/easy/0.10/testchain/chains/1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79/entries/9aec611c2f7b309b3171d61eb54ad8052c2a80c7a5ef9804544cc2ce84e3d094' -i -H 'Authorization: Bearer example-a108-250e-804e-4ed13b543b30' -H 'Content-Type: application/json'

7.1.21. Get the entry after the supplied entry Id (the next) in the provided chain

GET /{context}/chains/{chainId}/entries/{entryId}/next
Description

Get the entry after the supplied entry Id (the next) in the provided chain

Parameters
Type Name Description Schema

Path

chainId
required

chainId

string

Path

context
required

context

string

Path

entryId
required

entryId

string

Query

currentAnchorTime
optional

string (date-time)

Responses
HTTP Code Description Schema

200

The existing next entry

AnchoredEntryResponse

400

Invalid chain id

ErrorResponse

404

Entry does not exists

ErrorResponse

Consumes
  • application/json

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
GET /blockchain/easy/0.10/testchain/chains/1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79/entries/afcc331d5325111e7ee478f2dfd506b9a7b009784e3866adac2d579edbd05063/next HTTP/1.1
Authorization: Bearer example-a108-250e-804e-4ed13b543b30
Content-Type: application/json
Host: gw.api.cloud.sphereon.com
Example HTTP response
HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache
Expires: 0
Content-Type: application/json;charset=UTF-8
Content-Length: 1761

{
  "anchorState" : "ANCHORED",
  "anchorTimes" : [ "2018-08-14T02:04:52+02:00" ],
  "anchoredEntry" : {
    "chainId" : "1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79",
    "entry" : {
      "entryData" : {
        "content" : "Mm5kIEVudHJ5IENvbnRlbnQ=",
        "externalIds" : [ {
          "value" : "Mm5kIGVudHJ5IGV4dGVybmFsIGlkIDE="
        }, {
          "value" : "Mm5kIGVudHJ5IGV4dGVybmFsIGlkIDI="
        } ]
      }
    },
    "entryId" : "5ed61fab9c58d4bcf7c30cdd0dd4887331353f7ec7b8c905fe2d066de1c25836",
    "rawBackendStructure" : "{\r\n  \"error\" : null,\r\n  \"id\" : 20,\r\n  \"result\" : {\r\n    \"blockhash\" : \"00c61e9364fe84b7fa727b79e7c5a8106ff8b5e3e327f88acb840ec45f4e5ae4\",\r\n    \"blockindex\" : 3,\r\n    \"blocktime\" : 1534205092,\r\n    \"confirmations\" : 2,\r\n    \"data\" : \"7b0d0a202022636f6e74656e7422203a20224d6d356b4945567564484a3549454e76626e526c626e513d222c0d0a20202265787465726e616c49647322203a205b207b0d0a202020202276616c756522203a20224d6d356b4947567564484a354947563464475679626d467349476c6b4944453d220d0a20207d2c207b0d0a202020202276616c756522203a20224d6d356b4947567564484a354947563464475679626d467349476c6b4944493d220d0a20207d205d0d0a7d\",\r\n    \"key\" : \"5ed61fab9c58d4bcf7c30cdd0dd4887331353f7ec7b8c905fe2d066de1c25836\",\r\n    \"publishers\" : [ \"1Lj7C69vHBzDvyDx8NPrEYo7iwcDNHvnb1joYY\" ],\r\n    \"time\" : 1534205076,\r\n    \"timereceived\" : 1534205076,\r\n    \"txid\" : \"6273186ac8e884f5701d88b3ae93336eabb9865db5fdd0a68de9395940ef355f\",\r\n    \"valid\" : true,\r\n    \"vout\" : 0\r\n  }\r\n}"
  },
  "currentAnchorTime" : "2018-08-14T02:04:52+02:00",
  "firstAnchorTime" : "2018-08-14T02:04:52+02:00",
  "lastAnchorTime" : "2018-08-14T02:04:52+02:00"
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/blockchain/easy/0.10/testchain/chains/1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79/entries/afcc331d5325111e7ee478f2dfd506b9a7b009784e3866adac2d579edbd05063/next' -i -H 'Authorization: Bearer example-a108-250e-804e-4ed13b543b30' -H 'Content-Type: application/json'

7.1.22. Get the entry before the supplied entry Id (the previous) in the provided chain

GET /{context}/chains/{chainId}/entries/{entryId}/previous
Description

Get the entry before the supplied entry Id (the previous) in the provided chain

Parameters
Type Name Description Schema

Path

chainId
required

chainId

string

Path

context
required

context

string

Path

entryId
required

entryId

string

Query

currentAnchorTime
optional

string (date-time)

Responses
HTTP Code Description Schema

200

The existing previous entry

AnchoredEntryResponse

400

Invalid chain id

ErrorResponse

404

Entry does not exists

ErrorResponse

Consumes
  • application/json

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
GET /blockchain/easy/0.10/testchain/chains/1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79/entries/9aec611c2f7b309b3171d61eb54ad8052c2a80c7a5ef9804544cc2ce84e3d094/previous HTTP/1.1
Authorization: Bearer example-a108-250e-804e-4ed13b543b30
Content-Type: application/json
Host: gw.api.cloud.sphereon.com
Example HTTP response
HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache
Expires: 0
Content-Type: application/json;charset=UTF-8
Content-Length: 1761

{
  "anchorState" : "ANCHORED",
  "anchorTimes" : [ "2018-08-14T02:04:52+02:00" ],
  "anchoredEntry" : {
    "chainId" : "1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79",
    "entry" : {
      "entryData" : {
        "content" : "Mm5kIEVudHJ5IENvbnRlbnQ=",
        "externalIds" : [ {
          "value" : "Mm5kIGVudHJ5IGV4dGVybmFsIGlkIDE="
        }, {
          "value" : "Mm5kIGVudHJ5IGV4dGVybmFsIGlkIDI="
        } ]
      }
    },
    "entryId" : "5ed61fab9c58d4bcf7c30cdd0dd4887331353f7ec7b8c905fe2d066de1c25836",
    "rawBackendStructure" : "{\r\n  \"error\" : null,\r\n  \"id\" : 25,\r\n  \"result\" : {\r\n    \"blockhash\" : \"00c61e9364fe84b7fa727b79e7c5a8106ff8b5e3e327f88acb840ec45f4e5ae4\",\r\n    \"blockindex\" : 3,\r\n    \"blocktime\" : 1534205092,\r\n    \"confirmations\" : 2,\r\n    \"data\" : \"7b0d0a202022636f6e74656e7422203a20224d6d356b4945567564484a3549454e76626e526c626e513d222c0d0a20202265787465726e616c49647322203a205b207b0d0a202020202276616c756522203a20224d6d356b4947567564484a354947563464475679626d467349476c6b4944453d220d0a20207d2c207b0d0a202020202276616c756522203a20224d6d356b4947567564484a354947563464475679626d467349476c6b4944493d220d0a20207d205d0d0a7d\",\r\n    \"key\" : \"5ed61fab9c58d4bcf7c30cdd0dd4887331353f7ec7b8c905fe2d066de1c25836\",\r\n    \"publishers\" : [ \"1Lj7C69vHBzDvyDx8NPrEYo7iwcDNHvnb1joYY\" ],\r\n    \"time\" : 1534205076,\r\n    \"timereceived\" : 1534205076,\r\n    \"txid\" : \"6273186ac8e884f5701d88b3ae93336eabb9865db5fdd0a68de9395940ef355f\",\r\n    \"valid\" : true,\r\n    \"vout\" : 0\r\n  }\r\n}"
  },
  "currentAnchorTime" : "2018-08-14T02:04:52+02:00",
  "firstAnchorTime" : "2018-08-14T02:04:52+02:00",
  "lastAnchorTime" : "2018-08-14T02:04:52+02:00"
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/blockchain/easy/0.10/testchain/chains/1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79/entries/9aec611c2f7b309b3171d61eb54ad8052c2a80c7a5ef9804544cc2ce84e3d094/previous' -i -H 'Authorization: Bearer example-a108-250e-804e-4ed13b543b30' -H 'Content-Type: application/json'

7.2. Backend

Backend related APIs

7.2.1. Create a new backend

POST /backends
Description

Create a new backend. A Backend is the link to one blockchain implementation and it' s nodes. Unless you create your own private blockchain network, you should not have to create a new backend. Just use one of the public backends available.

Parameters
Type Name Description Schema

Body

backend
required

backend

Backend

Responses
HTTP Code Description Schema

202

Backend creation request received

Backend

400

Invalid backend request

ErrorResponse

401

Backend request not allowed

ErrorResponse

Consumes
  • application/json;charset=UTF-8

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
POST /blockchain/easy/0.10/backends HTTP/1.1
Authorization: Bearer example-a108-250e-804e-4ed13b543b30
Content-Type: application/json
Host: gw.api.cloud.sphereon.com
Content-Length: 779

{
  "apiVersion" : 1,
  "dataStructure" : "MULTICHAIN",
  "end" : "2020-12-24T02:04:35.192+02:00",
  "externalAccess" : {
    "blackList" : [ ],
    "modes" : [ "PUBLIC", "READ", "WRITE" ],
    "whiteList" : [ ]
  },
  "id" : "2f965a75-8c86-491b-9f17-06603883bfe8",
  "name" : "example-backend",
  "owner" : "example-owner",
  "rpcProviders" : [ {
    "access" : {
      "blackList" : [ ],
      "modes" : [ ],
      "whiteList" : [ ]
    },
    "host" : "http://localhost:8331",
    "id" : "3d2ce1a9-6ca3-478c-8b1b-2bbeb768b150",
    "ledgerName" : "example",
    "owner" : "example-owner",
    "ownerType" : "CUSTOMER",
    "password" : "password",
    "type" : "API",
    "username" : "username"
  } ],
  "start" : "2018-08-09T02:04:35.191+02:00"
}
Example HTTP response
HTTP/1.1 202 Accepted
Content-Type: application/json;charset=UTF-8
Content-Length: 608

{
  "apiVersion" : 1,
  "dataStructure" : "MULTICHAIN",
  "end" : "2020-12-24T00:04:35.192Z",
  "externalAccess" : {
    "blackList" : [ ],
    "modes" : [ "PUBLIC", "READ", "WRITE" ],
    "whiteList" : [ ]
  },
  "id" : "c947eb75-5afb-4ff0-a065-dc2c03cde9a0",
  "name" : "example-backend",
  "rpcProviders" : [ {
    "access" : {
      "blackList" : [ ],
      "modes" : [ ],
      "whiteList" : [ ]
    },
    "id" : "3d2ce1a9-6ca3-478c-8b1b-2bbeb768b150",
    "ledgerName" : "example",
    "ownerType" : "CUSTOMER",
    "type" : "API"
  } ],
  "start" : "2018-08-09T00:04:35.191Z"
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/blockchain/easy/0.10/backends' -i -X POST -H 'Authorization: Bearer example-a108-250e-804e-4ed13b543b30' -H 'Content-Type: application/json' -d '{
  "apiVersion" : 1,
  "dataStructure" : "MULTICHAIN",
  "end" : "2020-12-24T02:04:35.192+02:00",
  "externalAccess" : {
    "blackList" : [ ],
    "modes" : [ "PUBLIC", "READ", "WRITE" ],
    "whiteList" : [ ]
  },
  "id" : "2f965a75-8c86-491b-9f17-06603883bfe8",
  "name" : "example-backend",
  "owner" : "example-owner",
  "rpcProviders" : [ {
    "access" : {
      "blackList" : [ ],
      "modes" : [ ],
      "whiteList" : [ ]
    },
    "host" : "http://localhost:8331",
    "id" : "3d2ce1a9-6ca3-478c-8b1b-2bbeb768b150",
    "ledgerName" : "example",
    "owner" : "example-owner",
    "ownerType" : "CUSTOMER",
    "password" : "password",
    "type" : "API",
    "username" : "username"
  } ],
  "start" : "2018-08-09T02:04:35.191+02:00"
}'

7.2.2. List backends

GET /backends
Description

List existing backends. Optionally including public backends of others. Please note that we never return sensitive information like password or rpc hosts. Even not for backend owners themselves

Parameters
Type Name Description Schema Default

Query

includePublic
optional

includePublic

boolean

"false"

Responses
HTTP Code Description Schema

200

List of backend

< Backend > array

400

Invalid backend request

ErrorResponse

401

Backend request not allowed

ErrorResponse

404

Backend not found

ErrorResponse

Consumes
  • application/json

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
GET /blockchain/easy/0.10/backends?includePublic=true HTTP/1.1
Authorization: Bearer example-a108-250e-804e-4ed13b543b30
Content-Type: application/json
Host: gw.api.cloud.sphereon.com
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1906

[ {
  "apiVersion" : 1,
  "dataStructure" : "MULTICHAIN",
  "end" : "2020-12-24T00:04:35.192Z",
  "externalAccess" : {
    "blackList" : [ ],
    "modes" : [ "PUBLIC", "READ", "WRITE" ],
    "whiteList" : [ ]
  },
  "id" : "c947eb75-5afb-4ff0-a065-dc2c03cde9a0",
  "name" : "example-backend",
  "rpcProviders" : [ {
    "access" : {
      "blackList" : [ ],
      "modes" : [ ],
      "whiteList" : [ ]
    },
    "id" : "3d2ce1a9-6ca3-478c-8b1b-2bbeb768b150",
    "ledgerName" : "example",
    "ownerType" : "CUSTOMER",
    "type" : "API"
  } ],
  "start" : "2018-08-09T00:04:35.191Z"
}, {
  "apiVersion" : 1,
  "dataStructure" : "MULTICHAIN",
  "end" : null,
  "externalAccess" : {
    "blackList" : [ ],
    "modes" : [ "READ", "WRITE", "PUBLIC" ],
    "whiteList" : [ ]
  },
  "id" : "multichain",
  "name" : "multichain",
  "rpcProviders" : [ {
    "access" : {
      "blackList" : [ ],
      "modes" : [ ],
      "whiteList" : [ ]
    },
    "id" : "9f5c7835-40b3-48a8-99d8-7429b43bab99",
    "ledgerName" : "testchain",
    "ownerType" : "PROVIDER",
    "type" : "API"
  } ],
  "start" : null
}, {
  "apiVersion" : 1,
  "dataStructure" : "FACTOM",
  "end" : null,
  "externalAccess" : {
    "blackList" : [ ],
    "modes" : [ "READ", "WRITE", "PUBLIC" ],
    "whiteList" : [ ]
  },
  "id" : "factom",
  "name" : "factom",
  "rpcProviders" : [ {
    "access" : {
      "blackList" : [ ],
      "modes" : [ ],
      "whiteList" : [ ]
    },
    "id" : "b4182bd7-3d95-402d-b0b1-7faf1a14de67",
    "ledgerName" : null,
    "ownerType" : "PROVIDER",
    "type" : "API"
  }, {
    "access" : {
      "blackList" : [ ],
      "modes" : [ ],
      "whiteList" : [ ]
    },
    "id" : "6b94ef11-4aa4-495a-aa05-28feb5e213b1",
    "ledgerName" : null,
    "ownerType" : "PROVIDER",
    "type" : "WALLET"
  } ],
  "start" : null
} ]
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/blockchain/easy/0.10/backends?includePublic=true' -i -H 'Authorization: Bearer example-a108-250e-804e-4ed13b543b30' -H 'Content-Type: application/json'

7.2.3. Get backend by id

GET /backends/{backendId}
Description

Get existing backend by id (not by name). Optionally including public backend of others. Please note that we never return sensitive information like password or rpc hosts. Even not for backend owners themselves

Parameters
Type Name Description Schema Default

Path

backendId
required

backendId

string

Query

includePublic
optional

includePublic

boolean

"false"

Responses
HTTP Code Description Schema

200

Backend

Backend

400

Invalid backend request

ErrorResponse

401

Backend request not allowed

ErrorResponse

404

Backend not found

ErrorResponse

Consumes
  • application/json

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
GET /blockchain/easy/0.10/backends/c947eb75-5afb-4ff0-a065-dc2c03cde9a0 HTTP/1.1
Authorization: Bearer example-a108-250e-804e-4ed13b543b30
Content-Type: application/json
Host: gw.api.cloud.sphereon.com
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 608

{
  "apiVersion" : 1,
  "dataStructure" : "MULTICHAIN",
  "end" : "2020-12-24T00:04:35.192Z",
  "externalAccess" : {
    "blackList" : [ ],
    "modes" : [ "PUBLIC", "READ", "WRITE" ],
    "whiteList" : [ ]
  },
  "id" : "c947eb75-5afb-4ff0-a065-dc2c03cde9a0",
  "name" : "example-backend",
  "rpcProviders" : [ {
    "access" : {
      "blackList" : [ ],
      "modes" : [ ],
      "whiteList" : [ ]
    },
    "id" : "3d2ce1a9-6ca3-478c-8b1b-2bbeb768b150",
    "ledgerName" : "example",
    "ownerType" : "CUSTOMER",
    "type" : "API"
  } ],
  "start" : "2018-08-09T00:04:35.191Z"
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/blockchain/easy/0.10/backends/c947eb75-5afb-4ff0-a065-dc2c03cde9a0' -i -H 'Authorization: Bearer example-a108-250e-804e-4ed13b543b30' -H 'Content-Type: application/json'

7.2.4. Delete a backend

DELETE /backends/{backendId}
Description

Delete backend by id (not by name)

Parameters
Type Name Description Schema

Path

backendId
required

backendId

string

Responses
HTTP Code Description Schema

200

Backend deleted

Backend

400

Invalid backend request

ErrorResponse

401

Backend request not allowed

ErrorResponse

404

Backend not found

ErrorResponse

Consumes
  • application/json

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
DELETE /blockchain/easy/0.10/backends/c947eb75-5afb-4ff0-a065-dc2c03cde9a0 HTTP/1.1
Authorization: Bearer example-a108-250e-804e-4ed13b543b30
Content-Type: application/json
Host: gw.api.cloud.sphereon.com
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 608

{
  "apiVersion" : 1,
  "dataStructure" : "MULTICHAIN",
  "end" : "2020-12-24T00:04:35.192Z",
  "externalAccess" : {
    "blackList" : [ ],
    "modes" : [ "PUBLIC", "READ", "WRITE" ],
    "whiteList" : [ ]
  },
  "id" : "c947eb75-5afb-4ff0-a065-dc2c03cde9a0",
  "name" : "example-backend",
  "rpcProviders" : [ {
    "access" : {
      "blackList" : [ ],
      "modes" : [ ],
      "whiteList" : [ ]
    },
    "id" : "3d2ce1a9-6ca3-478c-8b1b-2bbeb768b150",
    "ledgerName" : "example",
    "ownerType" : "CUSTOMER",
    "type" : "API"
  } ],
  "start" : "2018-08-09T00:04:35.191Z"
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/blockchain/easy/0.10/backends/c947eb75-5afb-4ff0-a065-dc2c03cde9a0' -i -X DELETE -H 'Authorization: Bearer example-a108-250e-804e-4ed13b543b30' -H 'Content-Type: application/json'

7.2.5. Find backends

GET /backends/{backendId}/find
Description

Find existing backend(s) by id (single result) and/or name (multiple results). Optionally including public backends of others. Please note that we never return sensitive information like password or rpc hosts. Even not for backend owners themselves

Parameters
Type Name Description Schema Default

Path

backendId
required

backendId

string

Query

includePublic
optional

includePublic

boolean

"false"

Responses
HTTP Code Description Schema

200

List of backend

< Backend > array

400

Invalid backend request

ErrorResponse

401

Backend request not allowed

ErrorResponse

404

Backend not found

ErrorResponse

Consumes
  • application/json

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
GET /blockchain/easy/0.10/backends/c947eb75-5afb-4ff0-a065-dc2c03cde9a0/find HTTP/1.1
Authorization: Bearer example-a108-250e-804e-4ed13b543b30
Content-Type: application/json
Host: gw.api.cloud.sphereon.com
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 612

[ {
  "apiVersion" : 1,
  "dataStructure" : "MULTICHAIN",
  "end" : "2020-12-24T00:04:35.192Z",
  "externalAccess" : {
    "blackList" : [ ],
    "modes" : [ "PUBLIC", "READ", "WRITE" ],
    "whiteList" : [ ]
  },
  "id" : "c947eb75-5afb-4ff0-a065-dc2c03cde9a0",
  "name" : "example-backend",
  "rpcProviders" : [ {
    "access" : {
      "blackList" : [ ],
      "modes" : [ ],
      "whiteList" : [ ]
    },
    "id" : "3d2ce1a9-6ca3-478c-8b1b-2bbeb768b150",
    "ledgerName" : "example",
    "ownerType" : "CUSTOMER",
    "type" : "API"
  } ],
  "start" : "2018-08-09T00:04:35.191Z"
} ]
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/blockchain/easy/0.10/backends/c947eb75-5afb-4ff0-a065-dc2c03cde9a0/find' -i -H 'Authorization: Bearer example-a108-250e-804e-4ed13b543b30' -H 'Content-Type: application/json'

7.3. Chain

Chain related APIs

7.3.1. Create a new chain

POST /{context}/chains
Description

Create a new chain. Create a new chain. You can regard a chain as a blockchain within a blockchain, All entries in a chain are linked and relies on data from previous entries in the chain.

Parameters
Type Name Description Schema

Path

context
required

context

string

Body

chain
required

Create a chain using the first entry supplied. The entry needs at least a (combination of) globaly unique external Id in the complete Blockchain network!

Chain

Responses
HTTP Code Description Schema

200

Chain already exists

CommittedChainResponse

202

Chain creation request received

CommittedChainResponse

400

Invalid blockchain request

ErrorResponse

Consumes
  • application/json;charset=UTF-8

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
POST /blockchain/easy/0.10/testchain/chains HTTP/1.1
Authorization: Bearer example-a108-250e-804e-4ed13b543b30
Content-Type: application/json
Host: gw.api.cloud.sphereon.com
Content-Length: 278

{
  "firstEntry" : {
    "entryData" : {
      "content" : "MXN0IEVudHJ5IENvbnRlbnQgKENoYWluKQ==",
      "externalIds" : [ {
        "value" : "MXN0IGV4dGVybmFsIGlkIEAgMTUzNDIwNTA3NTE5Mg=="
      }, {
        "value" : "MXN0IGV4dGVybmFsIGlkIDI="
      } ]
    }
  }
}
Example HTTP response
HTTP/1.1 202 Accepted
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache
Expires: 0
Content-Type: application/json;charset=UTF-8
Content-Length: 553

{
  "chain" : {
    "chain" : {
      "firstEntry" : {
        "entryData" : {
          "content" : "MXN0IEVudHJ5IENvbnRlbnQgKENoYWluKQ==",
          "externalIds" : [ {
            "value" : "MXN0IGV4dGVybmFsIGlkIEAgMTUzNDIwNTA3NTE5Mg=="
          }, {
            "value" : "MXN0IGV4dGVybmFsIGlkIDI="
          } ]
        }
      }
    },
    "id" : "1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79"
  },
  "commitTime" : "2018-08-14T02:04:35.946+02:00",
  "creationRequestTime" : "2018-08-14T02:04:35.943+02:00"
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/blockchain/easy/0.10/testchain/chains' -i -X POST -H 'Authorization: Bearer example-a108-250e-804e-4ed13b543b30' -H 'Content-Type: application/json' -d '{
  "firstEntry" : {
    "entryData" : {
      "content" : "MXN0IEVudHJ5IENvbnRlbnQgKENoYWluKQ==",
      "externalIds" : [ {
        "value" : "MXN0IGV4dGVybmFsIGlkIEAgMTUzNDIwNTA3NTE5Mg=="
      }, {
        "value" : "MXN0IGV4dGVybmFsIGlkIDI="
      } ]
    }
  }
}'

7.4. Context

Context and backend related APIs

7.4.1. Create context

POST /contexts
Description

Create a new context

Parameters
Type Name Description Schema

Body

context
required

context

Context

Responses
HTTP Code Description Schema

200

Context already exists

Context

202

Context creation request received

Context

400

Invalid context request

ErrorResponse

401

Backend request not allowed

ErrorResponse

Consumes
  • application/json;charset=UTF-8

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
POST /blockchain/easy/0.10/contexts HTTP/1.1
Authorization: Bearer example-a108-250e-804e-4ed13b543b30
Content-Type: application/json
Host: gw.api.cloud.sphereon.com
Content-Length: 225

{
  "access" : {
    "blackList" : [ ],
    "modes" : [ "READ", "WRITE" ],
    "whiteList" : [ ]
  },
  "backendIds" : [ "c947eb75-5afb-4ff0-a065-dc2c03cde9a0" ],
  "name" : "testchain",
  "owner" : "context-owner"
}
Example HTTP response
HTTP/1.1 202 Accepted
Content-Type: application/json;charset=UTF-8
Content-Length: 245

{
  "access" : {
    "blackList" : [ ],
    "modes" : [ "READ", "WRITE" ],
    "whiteList" : [ ]
  },
  "backendIds" : [ "c947eb75-5afb-4ff0-a065-dc2c03cde9a0" ],
  "id" : "8e0e9c9f-408b-406f-ae93-c42e7cc9fb79",
  "name" : "testchain"
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/blockchain/easy/0.10/contexts' -i -X POST -H 'Authorization: Bearer example-a108-250e-804e-4ed13b543b30' -H 'Content-Type: application/json' -d '{
  "access" : {
    "blackList" : [ ],
    "modes" : [ "READ", "WRITE" ],
    "whiteList" : [ ]
  },
  "backendIds" : [ "c947eb75-5afb-4ff0-a065-dc2c03cde9a0" ],
  "name" : "testchain",
  "owner" : "context-owner"
}'

7.4.2. Get context

GET /contexts/{context}
Description

Get an existing context

Parameters
Type Name Description Schema

Path

context
required

context

string

Responses
HTTP Code Description Schema

200

Context

Context

400

Invalid context request

ErrorResponse

404

Context not found

ErrorResponse

Consumes
  • application/json

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
GET /blockchain/easy/0.10/contexts/factom?includePublic=true HTTP/1.1
Authorization: Bearer example-a108-250e-804e-4ed13b543b30
Content-Type: application/json
Host: gw.api.cloud.sphereon.com
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 222

{
  "access" : {
    "blackList" : [ ],
    "modes" : [ "READ", "WRITE", "PUBLIC" ],
    "whiteList" : [ ]
  },
  "backendIds" : [ "factom" ],
  "id" : "22fe22f8-020f-459f-bdeb-0f49b8317445",
  "name" : "factom"
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/blockchain/easy/0.10/contexts/factom?includePublic=true' -i -H 'Authorization: Bearer example-a108-250e-804e-4ed13b543b30' -H 'Content-Type: application/json'

7.4.3. Delete context

DELETE /contexts/{context}
Description

Delete an existing context

Parameters
Type Name Description Schema

Path

context
required

context

string

Responses
HTTP Code Description Schema

200

The deleted context

Context

400

Invalid context request

ErrorResponse

404

Context not found

ErrorResponse

Consumes
  • application/json

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
DELETE /blockchain/easy/0.10/contexts/testchain HTTP/1.1
Authorization: Bearer example-a108-250e-804e-4ed13b543b30
Content-Type: application/json
Host: gw.api.cloud.sphereon.com
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 245

{
  "access" : {
    "blackList" : [ ],
    "modes" : [ "READ", "WRITE" ],
    "whiteList" : [ ]
  },
  "backendIds" : [ "c947eb75-5afb-4ff0-a065-dc2c03cde9a0" ],
  "id" : "8e0e9c9f-408b-406f-ae93-c42e7cc9fb79",
  "name" : "testchain"
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/blockchain/easy/0.10/contexts/testchain' -i -X DELETE -H 'Authorization: Bearer example-a108-250e-804e-4ed13b543b30' -H 'Content-Type: application/json'

7.5. Entry

Entry related APIs

7.5.1. Create a new entry in the provided chain

POST /{context}/chains/{chainId}/entries
Description

Create a new entry in the provided chain. The entry will be linked to the previous entry. If the entry already exists, the API will add an anchor time, since the entry Id would be the same as the previously registered entry

Parameters
Type Name Description Schema

Path

chainId
required

chainId

string

Path

context
required

context

string

Query

currentAnchorTime
optional

string (date-time)

Body

entry
required

Create a new entry for the specified chain

Entry

Responses
HTTP Code Description Schema

200

Entry already exists

CommittedEntryResponse

202

Entry creation request received

CommittedEntryResponse

400

Invalid entry request

ErrorResponse

404

Chain does not exist (yet)

ErrorResponse

Consumes
  • application/json;charset=UTF-8

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
POST /blockchain/easy/0.10/testchain/chains/1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79/entries HTTP/1.1
Authorization: Bearer example-a108-250e-804e-4ed13b543b30
Content-Type: application/json
Host: gw.api.cloud.sphereon.com
Content-Length: 221

{
  "entryData" : {
    "content" : "M3JkIEVudHJ5IENvbnRlbnQ=",
    "externalIds" : [ {
      "value" : "M3JkIGVudHJ5IGV4dGVybmFsIGlkIDE="
    }, {
      "value" : "M3JkIGVudHJ5IGV4dGVybmFsIGlkIDI="
    } ]
  }
}
Example HTTP response
HTTP/1.1 202 Accepted
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache
Expires: 0
Content-Type: application/json;charset=UTF-8
Content-Length: 613

{
  "commitTime" : "2018-08-14T02:04:36.355+02:00",
  "creationRequestTime" : "2018-08-14T02:04:36.355+02:00",
  "entry" : {
    "chainId" : "1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79",
    "entry" : {
      "entryData" : {
        "content" : "M3JkIEVudHJ5IENvbnRlbnQ=",
        "externalIds" : [ {
          "value" : "M3JkIGVudHJ5IGV4dGVybmFsIGlkIDE="
        }, {
          "value" : "M3JkIGVudHJ5IGV4dGVybmFsIGlkIDI="
        } ]
      }
    },
    "entryId" : "9aec611c2f7b309b3171d61eb54ad8052c2a80c7a5ef9804544cc2ce84e3d094",
    "rawBackendStructure" : null
  }
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/blockchain/easy/0.10/testchain/chains/1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79/entries' -i -X POST -H 'Authorization: Bearer example-a108-250e-804e-4ed13b543b30' -H 'Content-Type: application/json' -d '{
  "entryData" : {
    "content" : "M3JkIEVudHJ5IENvbnRlbnQ=",
    "externalIds" : [ {
      "value" : "M3JkIGVudHJ5IGV4dGVybmFsIGlkIDE="
    }, {
      "value" : "M3JkIGVudHJ5IGV4dGVybmFsIGlkIDI="
    } ]
  }
}'

7.5.2. Get an existing entry in the provided chain

POST /{context}/chains/{chainId}/entries/entry
Description

Get an existing entry in the provided chain

Parameters
Type Name Description Schema

Path

chainId
required

chainId

string

Path

context
required

context

string

Query

currentAnchorTime
optional

string (date-time)

Body

entry
required

Retrieve the entry

Entry

Responses
HTTP Code Description Schema

200

The existing request entry

AnchoredEntryResponse

400

Invalid chain id

ErrorResponse

404

Request entry does not exists

AnchoredEntryResponse

Consumes
  • application/json

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

7.5.3. Get the entry after the supplied entry Id (the next) in the provided chain

POST /{context}/chains/{chainId}/entries/entry/next
Description

Get the entry after the supplied entry Id (the next) in the provided chain

Parameters
Type Name Description Schema

Path

chainId
required

chainId

string

Path

context
required

context

string

Query

currentAnchorTime
optional

string (date-time)

Body

entry
required

Retrieve the entry

Entry

Responses
HTTP Code Description Schema

200

The existing next entry

AnchoredEntryResponse

400

Invalid chain id

ErrorResponse

404

Request entry does not exists

AnchoredEntryResponse

Consumes
  • application/json

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

7.5.4. Get the entry before the supplied entry Id (the previous) in the provided chain

POST /{context}/chains/{chainId}/entries/entry/previous
Description

Get the entry before the supplied entry Id (the previous) in the provided chain

Parameters
Type Name Description Schema

Path

chainId
required

chainId

string

Path

context
required

context

string

Query

currentAnchorTime
optional

string (date-time)

Body

entry
required

Retrieve the entry

Entry

Responses
HTTP Code Description Schema

200

The existing previous entry

AnchoredEntryResponse

400

Invalid chain id

ErrorResponse

404

Request entry does not exists

AnchoredEntryResponse

Consumes
  • application/json

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

7.5.5. Get the first entry in the provided chain

GET /{context}/chains/{chainId}/entries/first
Description

Get the first entry in the provided chain. This is the oldest entry also called the chain tail. Please note that the achorTimes will only contain the first anchor time. Call getEntry to retrieve all times

Parameters
Type Name Description Schema

Path

chainId
required

chainId

string

Path

context
required

context

string

Responses
HTTP Code Description Schema

200

The existing anchored first entry

AnchoredEntryResponse

400

Invalid chain id

ErrorResponse

404

Entry does not exists

ErrorResponse

Consumes
  • application/json

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
GET /blockchain/easy/0.10/testchain/chains/1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79/entries/first HTTP/1.1
Authorization: Bearer example-a108-250e-804e-4ed13b543b30
Content-Type: application/json
Host: gw.api.cloud.sphereon.com
Example HTTP response
HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache
Expires: 0
Content-Type: application/json;charset=UTF-8
Content-Length: 1809

{
  "anchorState" : "ANCHORED",
  "anchorTimes" : [ "2018-08-14T02:04:52+02:00" ],
  "anchoredEntry" : {
    "chainId" : "1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79",
    "entry" : {
      "entryData" : {
        "content" : "MXN0IEVudHJ5IENvbnRlbnQgKENoYWluKQ==",
        "externalIds" : [ {
          "value" : "MXN0IGV4dGVybmFsIGlkIEAgMTUzNDIwNTA3NTE5Mg=="
        }, {
          "value" : "MXN0IGV4dGVybmFsIGlkIDI="
        } ]
      }
    },
    "entryId" : "afcc331d5325111e7ee478f2dfd506b9a7b009784e3866adac2d579edbd05063",
    "rawBackendStructure" : "{\r\n  \"error\" : null,\r\n  \"id\" : 14,\r\n  \"result\" : {\r\n    \"blockhash\" : \"00c61e9364fe84b7fa727b79e7c5a8106ff8b5e3e327f88acb840ec45f4e5ae4\",\r\n    \"blockindex\" : 2,\r\n    \"blocktime\" : 1534205092,\r\n    \"confirmations\" : 2,\r\n    \"data\" : \"7b0d0a202022636f6e74656e7422203a20224d584e304945567564484a3549454e76626e526c626e51674b454e6f59576c754b513d3d222c0d0a20202265787465726e616c49647322203a205b207b0d0a202020202276616c756522203a20224d584e304947563464475679626d467349476c6b494541674d54557a4e4449774e5441334e5445354d673d3d220d0a20207d2c207b0d0a202020202276616c756522203a20224d584e304947563464475679626d467349476c6b4944493d220d0a20207d205d0d0a7d\",\r\n    \"key\" : \"afcc331d5325111e7ee478f2dfd506b9a7b009784e3866adac2d579edbd05063\",\r\n    \"publishers\" : [ \"1Lj7C69vHBzDvyDx8NPrEYo7iwcDNHvnb1joYY\" ],\r\n    \"time\" : 1534205076,\r\n    \"timereceived\" : 1534205076,\r\n    \"txid\" : \"bd1592557da0026bc7f11b2e2ccb50a27feaf98d3febced7bc2ef2712c419ef1\",\r\n    \"valid\" : true,\r\n    \"vout\" : 0\r\n  }\r\n}"
  },
  "currentAnchorTime" : "2018-08-14T02:04:52+02:00",
  "firstAnchorTime" : "2018-08-14T02:04:52+02:00",
  "lastAnchorTime" : "2018-08-14T02:04:52+02:00"
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/blockchain/easy/0.10/testchain/chains/1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79/entries/first' -i -H 'Authorization: Bearer example-a108-250e-804e-4ed13b543b30' -H 'Content-Type: application/json'

7.5.6. Get the last entry in the provided chain.

GET /{context}/chains/{chainId}/entries/last
Description

Get the last entry in the provided chain. This is the most recent entry also called the chain head. Please note that the achorTimes will only contain the latest anchor time. Call getEntry to retrieve all times

Parameters
Type Name Description Schema

Path

chainId
required

chainId

string

Path

context
required

context

string

Responses
HTTP Code Description Schema

200

The existing anchored entry

AnchoredEntryResponse

400

Invalid chain id

ErrorResponse

404

Entry does not exists

ErrorResponse

Consumes
  • application/json

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
GET /blockchain/easy/0.10/testchain/chains/1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79/entries/last HTTP/1.1
Authorization: Bearer example-a108-250e-804e-4ed13b543b30
Content-Type: application/json
Host: gw.api.cloud.sphereon.com
Example HTTP response
HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache
Expires: 0
Content-Type: application/json;charset=UTF-8
Content-Length: 1761

{
  "anchorState" : "ANCHORED",
  "anchorTimes" : [ "2018-08-14T02:04:52+02:00" ],
  "anchoredEntry" : {
    "chainId" : "1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79",
    "entry" : {
      "entryData" : {
        "content" : "M3JkIEVudHJ5IENvbnRlbnQ=",
        "externalIds" : [ {
          "value" : "M3JkIGVudHJ5IGV4dGVybmFsIGlkIDE="
        }, {
          "value" : "M3JkIGVudHJ5IGV4dGVybmFsIGlkIDI="
        } ]
      }
    },
    "entryId" : "9aec611c2f7b309b3171d61eb54ad8052c2a80c7a5ef9804544cc2ce84e3d094",
    "rawBackendStructure" : "{\r\n  \"error\" : null,\r\n  \"id\" : 12,\r\n  \"result\" : {\r\n    \"blockhash\" : \"00c61e9364fe84b7fa727b79e7c5a8106ff8b5e3e327f88acb840ec45f4e5ae4\",\r\n    \"blockindex\" : 4,\r\n    \"blocktime\" : 1534205092,\r\n    \"confirmations\" : 2,\r\n    \"data\" : \"7b0d0a202022636f6e74656e7422203a20224d334a6b4945567564484a3549454e76626e526c626e513d222c0d0a20202265787465726e616c49647322203a205b207b0d0a202020202276616c756522203a20224d334a6b4947567564484a354947563464475679626d467349476c6b4944453d220d0a20207d2c207b0d0a202020202276616c756522203a20224d334a6b4947567564484a354947563464475679626d467349476c6b4944493d220d0a20207d205d0d0a7d\",\r\n    \"key\" : \"9aec611c2f7b309b3171d61eb54ad8052c2a80c7a5ef9804544cc2ce84e3d094\",\r\n    \"publishers\" : [ \"1Lj7C69vHBzDvyDx8NPrEYo7iwcDNHvnb1joYY\" ],\r\n    \"time\" : 1534205076,\r\n    \"timereceived\" : 1534205076,\r\n    \"txid\" : \"9e9a8c956fff10790ed0befd145b93b65297bc2428dfa8dae3833d72c2a18f25\",\r\n    \"valid\" : true,\r\n    \"vout\" : 0\r\n  }\r\n}"
  },
  "currentAnchorTime" : "2018-08-14T02:04:52+02:00",
  "firstAnchorTime" : "2018-08-14T02:04:52+02:00",
  "lastAnchorTime" : "2018-08-14T02:04:52+02:00"
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/blockchain/easy/0.10/testchain/chains/1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79/entries/last' -i -H 'Authorization: Bearer example-a108-250e-804e-4ed13b543b30' -H 'Content-Type: application/json'

7.5.7. Get an existing entry in the provided chain

GET /{context}/chains/{chainId}/entries/{entryId}
Description

Get an existing entry in the provided chain

Parameters
Type Name Description Schema

Path

chainId
required

chainId

string

Path

context
required

context

string

Path

entryId
required

entryId

string

Query

currentAnchorTime
optional

string (date-time)

Responses
HTTP Code Description Schema

200

The existing entry

AnchoredEntryResponse

400

Invalid chain id

ErrorResponse

404

Entry does not exists

ErrorResponse

Consumes
  • application/json

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
GET /blockchain/easy/0.10/testchain/chains/1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79/entries/9aec611c2f7b309b3171d61eb54ad8052c2a80c7a5ef9804544cc2ce84e3d094 HTTP/1.1
Authorization: Bearer example-a108-250e-804e-4ed13b543b30
Content-Type: application/json
Host: gw.api.cloud.sphereon.com
Example HTTP response
HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache
Expires: 0
Content-Type: application/json;charset=UTF-8
Content-Length: 1761

{
  "anchorState" : "ANCHORED",
  "anchorTimes" : [ "2018-08-14T02:04:52+02:00" ],
  "anchoredEntry" : {
    "chainId" : "1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79",
    "entry" : {
      "entryData" : {
        "content" : "M3JkIEVudHJ5IENvbnRlbnQ=",
        "externalIds" : [ {
          "value" : "M3JkIGVudHJ5IGV4dGVybmFsIGlkIDE="
        }, {
          "value" : "M3JkIGVudHJ5IGV4dGVybmFsIGlkIDI="
        } ]
      }
    },
    "entryId" : "9aec611c2f7b309b3171d61eb54ad8052c2a80c7a5ef9804544cc2ce84e3d094",
    "rawBackendStructure" : "{\r\n  \"error\" : null,\r\n  \"id\" : 10,\r\n  \"result\" : {\r\n    \"blockhash\" : \"00c61e9364fe84b7fa727b79e7c5a8106ff8b5e3e327f88acb840ec45f4e5ae4\",\r\n    \"blockindex\" : 4,\r\n    \"blocktime\" : 1534205092,\r\n    \"confirmations\" : 2,\r\n    \"data\" : \"7b0d0a202022636f6e74656e7422203a20224d334a6b4945567564484a3549454e76626e526c626e513d222c0d0a20202265787465726e616c49647322203a205b207b0d0a202020202276616c756522203a20224d334a6b4947567564484a354947563464475679626d467349476c6b4944453d220d0a20207d2c207b0d0a202020202276616c756522203a20224d334a6b4947567564484a354947563464475679626d467349476c6b4944493d220d0a20207d205d0d0a7d\",\r\n    \"key\" : \"9aec611c2f7b309b3171d61eb54ad8052c2a80c7a5ef9804544cc2ce84e3d094\",\r\n    \"publishers\" : [ \"1Lj7C69vHBzDvyDx8NPrEYo7iwcDNHvnb1joYY\" ],\r\n    \"time\" : 1534205076,\r\n    \"timereceived\" : 1534205076,\r\n    \"txid\" : \"9e9a8c956fff10790ed0befd145b93b65297bc2428dfa8dae3833d72c2a18f25\",\r\n    \"valid\" : true,\r\n    \"vout\" : 0\r\n  }\r\n}"
  },
  "currentAnchorTime" : "2018-08-14T02:04:52+02:00",
  "firstAnchorTime" : "2018-08-14T02:04:52+02:00",
  "lastAnchorTime" : "2018-08-14T02:04:52+02:00"
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/blockchain/easy/0.10/testchain/chains/1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79/entries/9aec611c2f7b309b3171d61eb54ad8052c2a80c7a5ef9804544cc2ce84e3d094' -i -H 'Authorization: Bearer example-a108-250e-804e-4ed13b543b30' -H 'Content-Type: application/json'

7.5.8. Get the entry after the supplied entry Id (the next) in the provided chain

GET /{context}/chains/{chainId}/entries/{entryId}/next
Description

Get the entry after the supplied entry Id (the next) in the provided chain

Parameters
Type Name Description Schema

Path

chainId
required

chainId

string

Path

context
required

context

string

Path

entryId
required

entryId

string

Query

currentAnchorTime
optional

string (date-time)

Responses
HTTP Code Description Schema

200

The existing next entry

AnchoredEntryResponse

400

Invalid chain id

ErrorResponse

404

Entry does not exists

ErrorResponse

Consumes
  • application/json

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
GET /blockchain/easy/0.10/testchain/chains/1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79/entries/afcc331d5325111e7ee478f2dfd506b9a7b009784e3866adac2d579edbd05063/next HTTP/1.1
Authorization: Bearer example-a108-250e-804e-4ed13b543b30
Content-Type: application/json
Host: gw.api.cloud.sphereon.com
Example HTTP response
HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache
Expires: 0
Content-Type: application/json;charset=UTF-8
Content-Length: 1761

{
  "anchorState" : "ANCHORED",
  "anchorTimes" : [ "2018-08-14T02:04:52+02:00" ],
  "anchoredEntry" : {
    "chainId" : "1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79",
    "entry" : {
      "entryData" : {
        "content" : "Mm5kIEVudHJ5IENvbnRlbnQ=",
        "externalIds" : [ {
          "value" : "Mm5kIGVudHJ5IGV4dGVybmFsIGlkIDE="
        }, {
          "value" : "Mm5kIGVudHJ5IGV4dGVybmFsIGlkIDI="
        } ]
      }
    },
    "entryId" : "5ed61fab9c58d4bcf7c30cdd0dd4887331353f7ec7b8c905fe2d066de1c25836",
    "rawBackendStructure" : "{\r\n  \"error\" : null,\r\n  \"id\" : 20,\r\n  \"result\" : {\r\n    \"blockhash\" : \"00c61e9364fe84b7fa727b79e7c5a8106ff8b5e3e327f88acb840ec45f4e5ae4\",\r\n    \"blockindex\" : 3,\r\n    \"blocktime\" : 1534205092,\r\n    \"confirmations\" : 2,\r\n    \"data\" : \"7b0d0a202022636f6e74656e7422203a20224d6d356b4945567564484a3549454e76626e526c626e513d222c0d0a20202265787465726e616c49647322203a205b207b0d0a202020202276616c756522203a20224d6d356b4947567564484a354947563464475679626d467349476c6b4944453d220d0a20207d2c207b0d0a202020202276616c756522203a20224d6d356b4947567564484a354947563464475679626d467349476c6b4944493d220d0a20207d205d0d0a7d\",\r\n    \"key\" : \"5ed61fab9c58d4bcf7c30cdd0dd4887331353f7ec7b8c905fe2d066de1c25836\",\r\n    \"publishers\" : [ \"1Lj7C69vHBzDvyDx8NPrEYo7iwcDNHvnb1joYY\" ],\r\n    \"time\" : 1534205076,\r\n    \"timereceived\" : 1534205076,\r\n    \"txid\" : \"6273186ac8e884f5701d88b3ae93336eabb9865db5fdd0a68de9395940ef355f\",\r\n    \"valid\" : true,\r\n    \"vout\" : 0\r\n  }\r\n}"
  },
  "currentAnchorTime" : "2018-08-14T02:04:52+02:00",
  "firstAnchorTime" : "2018-08-14T02:04:52+02:00",
  "lastAnchorTime" : "2018-08-14T02:04:52+02:00"
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/blockchain/easy/0.10/testchain/chains/1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79/entries/afcc331d5325111e7ee478f2dfd506b9a7b009784e3866adac2d579edbd05063/next' -i -H 'Authorization: Bearer example-a108-250e-804e-4ed13b543b30' -H 'Content-Type: application/json'

7.5.9. Get the entry before the supplied entry Id (the previous) in the provided chain

GET /{context}/chains/{chainId}/entries/{entryId}/previous
Description

Get the entry before the supplied entry Id (the previous) in the provided chain

Parameters
Type Name Description Schema

Path

chainId
required

chainId

string

Path

context
required

context

string

Path

entryId
required

entryId

string

Query

currentAnchorTime
optional

string (date-time)

Responses
HTTP Code Description Schema

200

The existing previous entry

AnchoredEntryResponse

400

Invalid chain id

ErrorResponse

404

Entry does not exists

ErrorResponse

Consumes
  • application/json

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
GET /blockchain/easy/0.10/testchain/chains/1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79/entries/9aec611c2f7b309b3171d61eb54ad8052c2a80c7a5ef9804544cc2ce84e3d094/previous HTTP/1.1
Authorization: Bearer example-a108-250e-804e-4ed13b543b30
Content-Type: application/json
Host: gw.api.cloud.sphereon.com
Example HTTP response
HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache
Expires: 0
Content-Type: application/json;charset=UTF-8
Content-Length: 1761

{
  "anchorState" : "ANCHORED",
  "anchorTimes" : [ "2018-08-14T02:04:52+02:00" ],
  "anchoredEntry" : {
    "chainId" : "1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79",
    "entry" : {
      "entryData" : {
        "content" : "Mm5kIEVudHJ5IENvbnRlbnQ=",
        "externalIds" : [ {
          "value" : "Mm5kIGVudHJ5IGV4dGVybmFsIGlkIDE="
        }, {
          "value" : "Mm5kIGVudHJ5IGV4dGVybmFsIGlkIDI="
        } ]
      }
    },
    "entryId" : "5ed61fab9c58d4bcf7c30cdd0dd4887331353f7ec7b8c905fe2d066de1c25836",
    "rawBackendStructure" : "{\r\n  \"error\" : null,\r\n  \"id\" : 25,\r\n  \"result\" : {\r\n    \"blockhash\" : \"00c61e9364fe84b7fa727b79e7c5a8106ff8b5e3e327f88acb840ec45f4e5ae4\",\r\n    \"blockindex\" : 3,\r\n    \"blocktime\" : 1534205092,\r\n    \"confirmations\" : 2,\r\n    \"data\" : \"7b0d0a202022636f6e74656e7422203a20224d6d356b4945567564484a3549454e76626e526c626e513d222c0d0a20202265787465726e616c49647322203a205b207b0d0a202020202276616c756522203a20224d6d356b4947567564484a354947563464475679626d467349476c6b4944453d220d0a20207d2c207b0d0a202020202276616c756522203a20224d6d356b4947567564484a354947563464475679626d467349476c6b4944493d220d0a20207d205d0d0a7d\",\r\n    \"key\" : \"5ed61fab9c58d4bcf7c30cdd0dd4887331353f7ec7b8c905fe2d066de1c25836\",\r\n    \"publishers\" : [ \"1Lj7C69vHBzDvyDx8NPrEYo7iwcDNHvnb1joYY\" ],\r\n    \"time\" : 1534205076,\r\n    \"timereceived\" : 1534205076,\r\n    \"txid\" : \"6273186ac8e884f5701d88b3ae93336eabb9865db5fdd0a68de9395940ef355f\",\r\n    \"valid\" : true,\r\n    \"vout\" : 0\r\n  }\r\n}"
  },
  "currentAnchorTime" : "2018-08-14T02:04:52+02:00",
  "firstAnchorTime" : "2018-08-14T02:04:52+02:00",
  "lastAnchorTime" : "2018-08-14T02:04:52+02:00"
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/blockchain/easy/0.10/testchain/chains/1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79/entries/9aec611c2f7b309b3171d61eb54ad8052c2a80c7a5ef9804544cc2ce84e3d094/previous' -i -H 'Authorization: Bearer example-a108-250e-804e-4ed13b543b30' -H 'Content-Type: application/json'

7.6. Id

Id determination and existence APIs

7.6.1. Predetermine id of chain

POST /{context}/chains/id
Description

Pre determine the Id of a chain without anchoring it in the blockchain. You determine the Id that the chain would receive once it would have been anchored

Parameters
Type Name Description Schema Default

Path

context
required

context

string

Query

checkExistence
optional

Check whether the id exists

boolean

"false"

Body

chain
required

Determine a chain hash. The entry needs at least a (combination of) globally unique external Id in the complete Blockchain network!

Chain

Responses
HTTP Code Description Schema

200

Chain request received and hash calculated

IdResponse

400

Invalid blockchain request

ErrorResponse

Consumes
  • application/json;charset=UTF-8

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
POST /blockchain/easy/0.10/testchain/chains/id?checkExistence=true HTTP/1.1
Authorization: Bearer example-a108-250e-804e-4ed13b543b30
Content-Type: application/json
Host: gw.api.cloud.sphereon.com
Content-Length: 278

{
  "firstEntry" : {
    "entryData" : {
      "content" : "MXN0IEVudHJ5IENvbnRlbnQgKENoYWluKQ==",
      "externalIds" : [ {
        "value" : "MXN0IGV4dGVybmFsIGlkIEAgMTUzNDIwNTA3NTE5Mg=="
      }, {
        "value" : "MXN0IGV4dGVybmFsIGlkIDI="
      } ]
    }
  }
}
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 103

{
  "Id" : "1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79",
  "exists" : "True"
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/blockchain/easy/0.10/testchain/chains/id?checkExistence=true' -i -X POST -H 'Authorization: Bearer example-a108-250e-804e-4ed13b543b30' -H 'Content-Type: application/json' -d '{
  "firstEntry" : {
    "entryData" : {
      "content" : "MXN0IEVudHJ5IENvbnRlbnQgKENoYWluKQ==",
      "externalIds" : [ {
        "value" : "MXN0IGV4dGVybmFsIGlkIEAgMTUzNDIwNTA3NTE5Mg=="
      }, {
        "value" : "MXN0IGV4dGVybmFsIGlkIDI="
      } ]
    }
  }
}'

7.6.2. Determine chain id exists

GET /{context}/chains/id/{chainId}
Description

Determine whether the Id of a chain exists in the blockchain

Parameters
Type Name Description Schema

Path

chainId
required

chainId

string

Path

context
required

context

string

Responses
HTTP Code Description Schema

200

Chain existence

IdResponse

400

Invalid blockchain request

ErrorResponse

Consumes
  • application/json

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
GET /blockchain/easy/0.10/testchain/chains/id/1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79 HTTP/1.1
Authorization: Bearer example-a108-250e-804e-4ed13b543b30
Content-Type: application/json
Host: gw.api.cloud.sphereon.com
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 103

{
  "Id" : "1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79",
  "exists" : "True"
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/blockchain/easy/0.10/testchain/chains/id/1c8dbe8f88188a4c1fcba864b3a21cd8c83521c78257f16aa936440862ae9e79' -i -H 'Authorization: Bearer example-a108-250e-804e-4ed13b543b30' -H 'Content-Type: application/json'

7.6.3. Predetermine id of an entry

POST /{context}/chains/id/{chainId}/entries
Description

Pre determine the Id of an entry request without anchoring the entry

Parameters
Type Name Description Schema Default

Path

chainId
required

chainId

string

Path

context
required

context

string

Query

checkExistence
optional

Check whether the id exists

boolean

"false"

Body

entry
required

The entry to determine the hash for on the specified chain

Entry

Responses
HTTP Code Description Schema

200

Entry request received and hash calculated

IdResponse

400

Invalid entry request

ErrorResponse

404

Invalid chain id. Only possible when existence is checked

ErrorResponse

Consumes
  • application/json;charset=UTF-8

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

7.6.4. Determine entry id exists

GET /{context}/chains/id/{chainId}/entries/{entryId}
Description

Determine whether the Id of an entry exists in the blockchain

Parameters
Type Name Description Schema

Path

chainId
required

chainId

string

Path

context
required

context

string

Path

entryId
required

entryId

string

Responses
HTTP Code Description Schema

200

Entry existence

IdResponse

400

Invalid blockchain request

ErrorResponse

404

Invalid chain id

ErrorResponse

Consumes
  • application/json

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

8. Security

8.1. oauth2schema

Type : oauth2
Flow : application
Token URL : https://gw.api.cloud.sphereon.com/token

Name Description

global

accessEverything

9. Definitions

9.1. Access

Name Schema

blackList
optional

< string > array

modes
optional

< enum (NONE, READ, WRITE, PUBLIC) > array

whiteList
optional

< string > array

9.2. AnchoredEntryResponse

Anchored Entry response

Name Description Schema

anchorState
required
read-only

enum (REQUESTED, COMMITTED, NOT_FOUND, ANCHORED)

anchorTimes
optional

All the times at which the Entry with the same Id was anchored in the blockchain in ISO 8601 format. The first, current and last Anchor Times will also be in this list

< string (date-time) > array

anchoredEntry
required

CommittedEntry

currentAnchorTime
optional
read-only

The current anchor time (this is not necessarely the last anchor time!) of the entry (if any) in the blockchain in ISO 8601 format

string (date-time)

firstAnchorTime
optional
read-only

The first anchor time of the entry (if any) in the blockchain in ISO 8601 format

string (date-time)

lastAnchorTime
optional
read-only

The last anchor time of the entry (if any) in the blockchain in ISO 8601 format

string (date-time)

9.3. Backend

A backend is a blockchain implementation along with it’s nodes (rpdProviders). You only need a backend when you wish to connect one of the supported blockchain implementations in a private blockchain. Otherwise use one of the public backends for your context

Name Description Schema

apiVersion
optional

integer (int32)

dataStructure
optional

enum (FACTOM, MULTICHAIN, ETHEREUM)

end
optional

string (date-time)

externalAccess
optional

Access

id
optional
read-only

string

name
required

The name of the backend.

string

rpcProviders
required

One or more nodes that comprise the blockchain backend

< RpcProvider > array

start
optional

string (date-time)

9.4. Chain

This is the Chain object itself. A chain is created with a first Entry. The chain Id is calculated from the firt Entry where the content part of the entry is omited during Chain ID calculation. After the chain is stored you can traverse the cahin using the API (not this object)

Name Description Schema

firstEntry
required

The First Entry with which this Chain was created. Traverse the chain using the API (not this object)

Entry

9.5. CommittedChain

Commited Chain

Name Description Schema

chain
optional

Chain

id
optional
read-only

Chain Id

string

9.6. CommittedChainResponse

Committed Chain response

Name Description Schema

chain
required

CommittedChain

commitTime
optional
read-only

The time at which the chain was first committed in ISO 8601 format

string (date-time)

creationRequestTime
optional
read-only

The time at which the chain creation was first requested in ISO 8601 format

string (date-time)

9.7. CommittedEntry

Committed Entry

Name Description Schema

chainId
optional
read-only

Chain ID

string

entry
optional

Entry

entryId
optional
read-only

Entry ID

string

rawBackendStructure
optional
read-only

Raw data structures of backend

string

9.8. CommittedEntryResponse

Committed EntryData response

Name Description Schema

commitTime
optional
read-only

The time at which the entry creation was first requested in ISO 8601 format

string (date-time)

creationRequestTime
optional
read-only

The time at which the entry creation was first requested in ISO 8601 format

string (date-time)

entry
required

CommittedEntry

9.9. Context

Name Description Schema

access
optional

Access

backendIds
required

The backend Ids used in this context. Currently only one backend is supported. The first backend Id supplied will be used. In the future it will be possible to connect multiple backends to one context. Only use the backend Ids, not the names here!

< string > array

id
optional
read-only

string

name
required

The name of the context as it is being used in the url. Please regard case! Because of the nature of the context within the API, the context name has to be globally unique amongst tenants!

string

9.10. Entry

Entry

Name Description Schema

entryData
required

The Entry Data

Entry Data

9.11. Entry Data

Entry Data contains the actual content and a list of External IDs (metadata)

Name Description Schema

content
optional

Content

string (byte)

externalIds
optional

External Ids

< External Id > array

9.12. Error

An error

Name Schema

cause
optional

Error

code
required

string

level
required

enum (INFO, WARNING, FATAL)

message
required

string

9.13. ErrorResponse

The error response

Name Schema

errors
optional

< Error > array

9.14. External Id

External Id: Allows you to store metadata. External Id bytes are included during Chain Id and Entry Id calculation

Name Description Schema

value
optional

Metadata value

string (byte)

9.15. IdResponse

Id response

Name Description Schema

Id
optional

The Id

string

exists
required

enum (True, False, Unknown)

9.16. RpcProvider

RpcProvider

Name Schema

access
optional

Access

host
optional

string

id
optional

string

ledgerName
optional

string

metaData
optional

< string, string > map

ownerType
optional

enum (PROVIDER, CUSTOMER)

password
optional

string

resourceFiles
optional

< string, string > map

type
optional

enum (API, WALLET)

username
optional

string

walletInfo
optional

string