Introduction

Welcome to Dedoco Trust Engine API Specifications for Developers!

This document contains the API specifications for integration with the Dedoco Trust Engine.

Version History

Whitepaper

A. API Developer Account

To have access to our Trust Engine API, please provide the following information and submit your application request to delab@dedoco.com.

Name of Organization:
Business Address:
Business Country:
Business Website URL:

Contact Person (Full Name):
Contact Person (Email):
Contact Person (Mobile):

Application Name:
Application Description/Use Case:
Application Type: [ Internal Use | Public SaaS | Enterprise App | Development | Testing | Others ]
Application URL:

After your application has been reviewed and approved, you will receive an email containing the API key for accessing the Trust Engine API.

B. Quickstart

Get a listing of all available contracts

curl -XGET 'https://dte.dedoco.com/v1/contracts' \
        -H 'Authorization: Bearer <api_key>'

Create a namespace

curl -XPOST 'https://dte.dedoco.com/v1/namespaces' \
         -H 'Authorization: Bearer <api_key>' \
         -H 'Content-Type: application/json' \
         -d '{
                "chain": "mumbai",
                "name": "test/v1"
                "type": "process/v2"
            }'

Create a process

curl -XPOST 'https://dte.dedoco.com/v1/processes' \
         -H 'Authorization: Bearer <api_key>' \
         -H 'Content-Type: application/json' \
         -d '{
              "contract": "test/v1",
              "publicMeta": {
                "k1": "v1"
              },
              "privateMeta": {
                "k2": "v2"
              }
            }'

Sign the process

curl -XPOST 'https://dte.dedoco.com/v1/processes/${processId}/events' \
         -H 'Authorization Bearer <api_key>' \
         -H 'Content-Type: application/json' \
         -d '{
              "contract": "test/v1",
              "publicMeta": {
                "k3": "v3"
              },
              "privateMeta": {
                "k4": "v4"
              }
            }'

Query

curl -XGET 'https://dte.dedoco.com/v1/processes/${processId}' \
        -H 'Authorization Bearer <api_key>'

curl -XGET 'https://dte.dedoco.com/v1/query/process?process.k1=v1' \
        -H 'Authorization Bearer <api_key>'

curl -XGET 'https://dte.dedoco.com/v1/query/process?signature.k3=v3' \
        -H 'Authorization Bearer <api_key>'`

1. Request for an API key from delab@dedoco.com.
2. Use the API key as Bearer Auth in subsequent requests.
3. Apply the sample code on the right hand side of this page.

C. Environments

Stage

Base URL

https://dte.stage.dedoco.com/v1

Prod

Base URL

https://dte.dedoco.com/v1

D. Concepts

The Trust Engine is a web2 >> web3 on-ramp for data-centric blockchain applications. The intention is to provide a simple web2 API that "just works" without the developer needing to think too much about web3 implications like contract management and indexing.

Here are some of the important concepts to understand.

Namespace

A namespace is a data container attached to a specific smart contract.

When you perform API actions as this namespace, it will talk to that smart contract.

The contract you register on the namespace will determine what capabilities the namespace has. If you register your namespace as an audit/v1 contract, you will not be able to create processes.

Contracts

You only need to think about contracts when you register a namespace.

A contract type is an upgrade path for a number of contracts. For example, you can have the process contract type that can upgrade between process/v1, process/v2, etc.

E. Processes

The Process APIs are designed to model multi-stage business processes.

A Process is a document attached to a series of signatures. It can help you track all changes to a particular document.

You create a Process with an initial documentHash. From this initial hash, you use the sign APIs to transition to other hashes.

The process as well as each of the signatures can have either public or private metadata attached.

F. Authentication

Use API key as bearer token

-H 'Authorization: Bearer <api_key>'

For now, authentication is dead simple.

1. Request an API key from delab@dedoco.com.
2. You get the API key.
3. Pass in the API key as a bearer token for your API calls.

G. Contract APIs

Endpoint: Create Namespace

POST /namespaces
Create or upgrade a data namespace backed by a contract.

Authorization:
Bearer <api_key>

Content-Type:
application/json

Sample request:

curl -XPOST 'https://dte.dedoco.com/v1/namespaces' \
         -H 'Authorization: Bearer <api_key>' \
         -H 'Content-Type: application/json' \
         -d '{
              "chain": "mumbai",
              "name": "test/v1"
              "contract": "process/v2"
            }'

Parameters:

Sample response:

{
  "address": "0x...."
}

Responses:

Endpoint: Add User to Namespace

POST /namespaces/users
Add a user to a namespace.

Authorization:
Bearer <api_key>

Content-Type:
application/json

Parameters:

Responses:

Endpoint: Get Namespaces

GET /namespaces
Get a listing of available namespaces.

Authorization:
Bearer <api_key>

Content-Type:
application/json

Sample request:

curl -XPOST 'https://dte.dedoco.com/v1/namespaces' \
         -H 'Authorization: Bearer <api_key>'

Parameters:

No parameters.

Sample response:

{
  namespaces: [
    {
      "name": "test/v1",
      "chain": "mumbai",
      "type": "process/v2",
      "address": "0x..."
    }
    ...
  ]
}

Responses:

Endpoint: Get Contracts

GET /contracts
Get a listing of available contracts.

Authorization:
Bearer <api_key>

Content-Type:
application/json

Sample request:

curl -XPOST 'https://dte.dedoco.com/v1/contracts' \
         -H 'Authorization: Bearer <api_key>'

Parameters:

No parameters.

Sample response:

{
  results: [
    {
      "type": "process"
      "versions": [
        {"key": "process/v1"},
        {"key": "process/v2"}
      ]
    }
    ...
  ]
}

Responses:

Endpoint: Create Custom Network

GET /networks
Create a custom network.

Authorization:
Bearer <api_key>

Content-Type:
application/json

Parameters:

Responses:

H. Process APIs

The process APIs refer to process/* contracts.

Endpoint: Create Process

POST /processes
Create a new process.

Authorization:
Bearer <api_key>

Content-Type:
application/json

Sample request:

curl -XPOST 'https://dte.dedoco.com/v1/processes' \
         -H 'Authorization: Bearer <api_key>' \
         -H 'Content-Type: application/json' \
         -d '{
              "namespace": "test/v1",
              "publicMeta": {
                "k1": "v1"
              },
              "privateMeta": {
                "k2": "v2"
              }
            }'

Parameters:

Sample response:

{
  "id": "5f....",
  "transactionHash": "0x..."
}

Responses:

Endpoint: Add User to Process

POST /processes/{processId}/users
Add a user to a process.

Authorization:
Bearer <api_key>

Content-Type:
application/json

Parameters:

Responses:

Endpoint: Add Event to Process

POST /processes/{processId}/events
Add a signature to a process.

Authorization:
Bearer <api_key>

Content-Type:
application/json

Sample request:

curl -XPOST 'https://dte.dedoco.com/v1/processes/{processId}/events' \
         -H 'Authorization: Bearer <api_key>' \
         -H 'Content-Type: application/json' \
         -d '{
              "publicMeta": {
                "k3": "v3"
              },
              "privateMeta": {
                "k4": "v4"
              }
            }'

Parameters:

Sample response:

{
  "transactionHash": "0x..."
}

Responses:

Endpoint: Get Process

GET /processes/{processId}
Get a process.

Authorization:
Bearer <api_key>

Content-Type:
application/json

Parameters:

No parameters.

Responses:

I. Query APIs

Endpoint: Query Process

GET /query/process
Query processes either by event or process metadata

Authorization:
Bearer <api_key>

Content-Type:
application/json

Sample request - query by event metadata:

curl -XGET 'https://dte.dedoco.com/v1/query/process?event.k3=v3' \
        -H 'Authorization: Bearer <api_key>'

Sample request - query by process metadata:

curl -XGET 'https://dte.dedoco.com/v1/query/process?process.k2=v2' \
        -H 'Authorization: Bearer <api_key>'

Query Parameters:

Sample response:

{
  processes: [
    {
      "id": "361bf3f495a84e7eb5d597b4e4cf3ebb",
      "namespace": {
        "name": "test/v1",
        "chain": "mumbai",
        "type": "process/v2"
      },
      # hash of transaction process was created
      "transactionHash": "0x332e5f69c96d21fdececa851761bb507e449888c687b7927672e67ce7f6ab583",
      # initial hash
      "documentHash": "0x125",
      "publicMeta": {
        "name": "test2"
      },
      "privateMeta": {
        "nric": "123124"
      },
      # or 'complete' depending on if it has been successfully indexed by Graph Protocol
      "status": "pending",
      "signatures": [
        {
          "transactionHash": "0xb0328d360d814540a54666f4958d10197d30cc583884a88983077eaa279d8174",
          "publicMeta": {
            "name": "test3",
            "description": "testing signatures"
          },
          "privateMeta": {
            "email": "jvrch@dedoco.com"
          },
          "fromHash": "0x125",
          "toHash": "0x126",
          "status": "pending"
        }
      ]
    }
    ...
  ]
}

Responses: