Hive Node API Documentation

Here is the documents for the APIs of the hive node. The hive node supports the following service:

  • authentication and authorization

  • the subscription of the vault service

  • the services under the vault: database, files, scripting, payment, backup

  • the subscription of the backup service

Summary

Resource

Operation

Description

01 Authentication

POST /api/v2/did/signin

Sign in with app instance DID

POST /api/v2/did/auth

Get the access token.

02 Subscription

PUT /api/v2/subscription/vault

Vault Subscribe

DELETE /api/v2/subscription/vault

Vault Unsubscribe

GET /api/v2/subscription/vault

Get Vault Info.

GET /api/v2/subscription/vault/app_stats

Get App Stats

POST /api/v2/subscription/vault

Activate&Deactivate

PUT /api/v2/subscription/backup

Backup Subscribe

DELETE /api/v2/subscription/backup

Backup Unsubscribe

GET /api/v2/subscription/backup

Get Backup Info.

GET /api/v2/subscription/pricing_plan

Get Vault Pricing Plans.

03 Database

GET /api/v2/vault/db/collections

Get collections

PUT /api/v2/vault/db/collections/(collection_name)

Create the collection

DELETE /api/v2/vault/db/(collection_name)

Delete the collection

POST /api/v2/vault/db/collection/(collection_name)

Insert&count the documents

PATCH /api/v2/vault/db/collection/(collection_name)

Update the documents

DELETE /api/v2/vault/db/collection/(collection_name)

Delete the documents

GET /api/v2/vault/db/(collection_name)

Find the documents

POST /api/v2/vault/db/query

Query the documents

04 Files

PUT /api/v2/vault/files/(path:path)

Copy/upload

PATCH /api/v2/vault/files/(path:path)

Move

DELETE /api/v2/vault/files/(path:path)

Delete

05 Scripting

PUT /api/v2/vault/scripting/(script_name)

Register

GET /api/v2/vault/scripting/scripts

Get Scripts

PATCH /api/v2/vault/scripting/(script_name)

Run Script

GET /api/v2/vault/scripting/(script_name)/(context_str)/(params)

Run Script URL

DELETE /api/v2/vault/scripting/(script_name)

Unregister

PUT /api/v2/vault/scripting/stream/(transaction_id)

Upload File

06 Backup

GET /api/v2/vault/content

Get the State

POST /api/v2/vault/content

Backup & Restore

POST /api/v2/backup/promotion

Promote

07 Payment

GET /api/v2/payment/version

Get Version

PUT /api/v2/payment/order

Place Order

POST /api/v2/payment/order/(order_id)

Settle Order

GET /api/v2/payment/order

Get Orders

GET /api/v2/payment/receipt

Get the Receipt

08 About

GET /api/v2/node/version

Get the Version

GET /api/v2/node/commit_id

Get the Commit ID

GET /api/v2/node/info

Get Node Information

09 Provider

GET /api/v2/provider/vaults

Get Vaults

GET /api/v2/provider/backups

Get Backups

GET /api/v2/provider/filled_orders

Get Payments

01 Auth

The authentication and authorization is for other hive node services.

For accessing the services of the node, signing in with the DID document of the application and getting the access token is first step.

To use the token returned by auth API. Please add this key-value in the header.

Authorization: token <the token returned by auth API>

sign in

POST /api/v2/did/signin

Sign in with the application instance DID to get the challenge string.

Request:

{
    "id": "<the user’s did_document>",
}

Response OK:

HTTP/1.1 201 Created
{
   “challenge”: “<the authentication challenge encoded in JWT>”
}

Response Error:

HTTP/1.1 400 Bad Request

auth

POST /api/v2/did/auth

Auth to get the access token for the user DID and the application DID.

Request:

{
    "challenge_response": "<the response for the authentication challenge encoded in JWT>",
}

Response OK:

HTTP/1.1 201 Created
{
    “token”: “<the access token encoded in JWT>”
}

Response Error:

HTTP/1.1 400 Bad Request

02 Subscription

subscription for the vault service and the backup service.

vault subscribe

PUT /api/v2/subscription/vault

Subscribe to a remote vault service on the specific hive node, where would create a new vault service if no such vault existed against the DID used.

A user can subscribe to only one vault service on the specific hive node with a given DID, then should declare that service endpoint on the DID document that would be published on the DID chain so that other users could be aware of the address and access the data on that vault with certain permission.

The free pricing plan is applied to a new subscribed vault. The payment APIs will be used for upgrading the vault service.

Request:

None

Response OK:

HTTP/1.1 200 OK
{
    "service_did": <hive node service did>
    "pricing_plan": <the using pricing plan>
    "storage_quota": 50000000, # the max space of the storage for the vault service.
    "storage_used": 0,
    "start_time": <the epoch time>,
    "end_time": <the epoch time>,
    "created": <the epoch time>,
    "updated": <the epoch time>,
    "app_count": <int>,
    "access_count": <int>,
    "access_amount": <int>,
    "access_last_time": <int>
}

Response Error:

HTTP/1.1 401 Unauthorized
HTTP/1.1 455 Already Exists

vault unsubscribe

DELETE /api/v2/subscription/vault

Unsubscribe from the remote vault service on a specific hive node. Only the vault owner can unsubscribe from his owned vault service. After unsubscription, the vault service would stop rendering service, and users can not access data from the vault anymore.

And the data on the vault would be unsafe and undefined or even deleted from the hive node.

URL Parameters:

force=<true|false> # true: delete all data of the vault permanently.

Request:

None

Response OK:

HTTP/1.1 204 No Content

Response Error:

HTTP/1.1 401 Unauthorized
HTTP/1.1 404 Not Found

get vault info.

GET /api/v2/subscription/vault

Get the information of the owned vault service.

The information contains something like storage usage, pricing plan, etc.

Request:

None

Response OK:

HTTP/1.1 200 OK
{
    "service_did": "did:elastos:ij8krAVRJitZKJmcCufoLHQjq7Mef3ZjTN",
    "pricing_plan": "Standard",
    "storage_quota": 524288000,
    "storage_used": 20,
    "start_time": <the epoch time>,
    "end_time": <the epoch time>,
    "created": <the epoch time>,
    "updated": <the epoch time>,
    "app_count": <int>,
    "access_count": <int>,
    "access_amount": <int>,
    "access_last_time": <int>
}

Response Error:

HTTP/1.1 401 Unauthorized
HTTP/1.1 404 Not Found

get app stats

GET /api/v2/subscription/vault/app_stats

Get all application stats in the user’s vault.

Request:

None

Response OK:

HTTP/1.1 200 OK
{
    "apps": [{
        "name": <str>,
        "developer_did": <str>
        "icon_url": <str>,
        "redirect_url": <str>,
        "user_did": <str>,
        "app_did": <str>,
        "used_storage_size": <int>,
        "access_count": <int>,
        "access_amount": <int>,
        "access_last_time": <int>
    }]
}

Response Error:

HTTP/1.1 400 Bad Request
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
HTTP/1.1 404 Not Found

activate & deactivate

POST /api/v2/subscription/vault

Activate or deactivate the vault

The vault can only be read when it is deactivated. This is very useful for do some operations on vault, like backup, promotion, ect.

Request:

None

Response OK:

HTTP/1.1 201 Created

Response Error:

HTTP/1.1 401 Unauthorized
HTTP/1.1 404 Not Found

backup subscribe

PUT /api/v2/subscription/backup

Subscribe to a remote backup service on the specific hive node. With the backup service, the data of the vault service can backup for data security.

Request:

None

Response OK:

HTTP/1.1 200 OK
{
     "service_did": "did:elastos:ij8krAVRJitZKJmcCufoLHQjq7Mef3ZjTN",
     "pricing_plan": "Standard",
     "storage_quota": 500,
     "storage_used": 20,
     "start_time": 1602236316, // epoch time.
     "end_time": 1602236316,
     "created": 1602236316,
     "updated": 1604914928
}

Response Error:

HTTP/1.1 401 Unauthorized
HTTP/1.1 455 Already Exists

backup unsubscribe

DELETE /api/v2/subscription/backup

Unsubscribe from the remote backup service on a specific hive node.

The data on the backup node would be unsafe and undefined or even deleted from the hive node.

Request:

None

Response OK:

HTTP/1.1 204 No Content

Response Error:

HTTP/1.1 401 Unauthorized
HTTP/1.1 404 Not Found

get backup info.

GET /api/v2/subscription/backup

Get the information of the owned backup service.

The information contains something like storage usage, pricing plan, etc.

Request:

None

Response OK:

HTTP/1.1 200 OK
{
     "service_did": "did:elastos:ij8krAVRJitZKJmcCufoLHQjq7Mef3ZjTN",
     "pricing_plan": "Standard",
     "storage_quota": 500,
     "storage_used": 20,
     "start_time": 1602236316, // epoch time.
     "end_time": 1602236316,
     "created": 1602236316,
     "updated": 1604914928
}

Response Error:

HTTP/1.1 401 Unauthorized
HTTP/1.1 404 Not Found

get pricing plans

GET /api/v2/subscription/pricing_plan

Get an available pricing plan list or the specific pricing plan for the vault and backup service.

The pricing plan list is the pricing plans that the hive node supported for the vault service. The owner of the vault service can use the pricing plan name upgrade the vault service to get much more storage space.

URL Parameters:

subscription=all # possible value: all, vault or backup
name=rookie # the pricing plan name

Response OK:

HTTP/1.1 200 OK
{
    "backupPlans": [{
            amount": 0,
                "currency": "ELA",
            "maxStorage": 500,
            "name": "Basic",
            "serviceDays": -1
        }, {
            "amount": 1.5,
            "currency": "ELA",
            "maxStorage": 2000,
            "name": "Standard",
             "serviceDays": 30
        }, {
            "amount": 3,
             "currency": "ELA",
            "maxStorage": 5000,
            "name": "Premium",
            "serviceDays": 30
        }],

    "pricingPlans": [{
        "amount": 0,
        "currency": "ELA",
        "maxStorage": 500,
        "name": "Basic",
        "serviceDays": -1
    }, {
        "amount": 2.5,
        "currency": "ELA",
        "maxStorage": 2000,
        "name": "Standard",
        "serviceDays": 30
    }, {
         "amount": 5,
        "currency": "ELA",
        "maxStorage": 5000,
        "name": "Premium",
        "serviceDays": 30
    }],
    "version": "1.0"
}

Response Error:

HTTP/1.1 401 Unauthorized
HTTP/1.1 404 Not Found

03 Database

based on mongodb.

get collections

GET /api/v2/vault/db/collections

Get all collections created by user.

Request:

None

Response OK:

HTTP/1.1 200 OK
{
    “collections”: [
        "name": <str>,
        "is_encrypt": <bool>,
        "encrypt_method": <str>
    ]
}

Response Error:

HTTP/1.1 400 Bad Request
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
HTTP/1.1 404 Not Found

create collection

PUT /api/v2/vault/db/collections/(collection_name)

Create the collection by collection name.

Request:

URL Parameters:

is_encrypt=<true|false>     # [optional] Whether the documents of the collection has been encrypted by hive sdk. Default is 'false'.
encrypt_method=<string>     # [optional] The way to encrypt. Default is empty string.

Response OK:

HTTP/1.1 200 OK
{
    “name”: “<collection_name>”
}

Response Error:

HTTP/1.1 400 Bad Request
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
HTTP/1.1 455 Already Exists
HTTP/1.1 507 Insufficient Storage

delete collection

DELETE /api/v2/vault/db/(collection_name)

Delete the collection by collection name.

Request:

None

Response OK:

HTTP/1.1 204 No Content

Response Error:

HTTP/1.1 400 Bad Request
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
HTTP/1.1 404 Not Found

insert or count documents

POST /api/v2/vault/db/collection/(collection_name)

Insert or count the documents.

Insert the documents if no URL parameters.

Request:

{
    "document": [
        {
            "author": "john doe1",
            "title": "Eve for Dummies1"
        },
        {
            "author": "john doe2",
            "title": "Eve for Dummies2"
         }
     ],
    "options": {  # optional
        "bypass_document_validation": false,
        "ordered": true,
        # Default true. If true, new fields [created, modified: int(timestamp)] will be added to each document.
        "timestamp": true
    }
}

Response OK:

HTTP/1.1 201 Created
{
    "acknowledged": true,
    "inserted_ids": [
        "5f4658d122c95b17e72f2d4a",
        "5f4658d122c95b17e72f2d4b"
    ]
}

Response Error:

HTTP/1.1 400 Bad Request
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
HTTP/1.1 404 Not Found
HTTP/1.1 507 Insufficient Storage

Count the documents if the URL parameter is op=count

Request:

{
    "filter": {
        "author": "john doe1_1",
    },
    "options": {
        "skip": 0,
        "limit": 10,
        "maxTimeMS": 1000000000
    }
}

Response OK:

HTTP/1.1 204 No Content
{
    "count": 10
}

Response Error:

HTTP/1.1 400 Bad Request
HTTP/1.1 401 Unauthorized
HTTP/1.1 404 Not Found

update documents

PATCH /api/v2/vault/db/collection/(collection_name)

Update the documents by collection name.

URL Parameters:

updateone=<true|false> # Whether update only one matched document. Default is false.

Request:

{
    "filter": {
        "author": "john doe1",
    },
    # This will update modified field if exists.
    "update": {
        "$set": {  # optional
            "author": "john doe1_1",
            "title": "Eve for Dummies1_1"
        }
    },
    "options": {  # optional
        "upsert": true,
        "bypass_document_validation": false,
        # Default true. If true, the field modified (if exists) will be updated to any matched documents.
        "timestamp": true
    }
}

Response OK:

HTTP/1.1 200 OK
{
    "acknowledged": true,
    "matched_count": 10,
    "modified_count": 10,
    "upserted_id": null
}

Response Error:

HTTP/1.1 400 Bad Request
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
HTTP/1.1 404 Not Found
HTTP/1.1 507 Insufficient Storage

delete documents

DELETE /api/v2/vault/db/collection/(collection_name)

Delete the documents by collection name.

URL Parameters:

deleteone=<true|false> # Whether delete only one matched document. Default is false.

Request:

{
    "filter": {
        "author": "john doe1",
    }
 }

Response OK:

HTTP/1.1 204 No Content

Response Error:

HTTP/1.1 400 Bad Request
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
HTTP/1.1 404 Not Found

find documents

GET /api/v2/vault/db/(collection_name)

Find the documents by collection name. The parameters are URL ones.

URL Parameters:

filter: (json str)  # the filter doc need to be encoded by url
skip: (int)         # optional
limit: (int)        # optional

Request:

None

Response OK:

HTTP/1.1 200 OK
{
    "items": [{
        "author": "john doe1_1",
        "title": "Eve for Dummies1_1",
        "created": {
            "$date": 1630022400000
        },
        "modified": {
            "$date": 1598803861786
        }
    }]
}

Response Error:

HTTP/1.1 400 Bad Request
HTTP/1.1 401 Unauthorized
HTTP/1.1 404 Not Found

query documents

POST /api/v2/vault/db/query

Query the documents with more options

Request:

{
    "collection": "works",
    "filter": {
        "author": "john doe1_1",
    },
    "options": {  # optional
        "skip": 0,
        "limit": 3,
        "projection": {
            "_id": false
        },
        "sort": [["_id", -1]], # -1: pymongo.DESCENDING, 1: pymongo.ASCENDING
        "allow_partial_results": false,
        "return_key": false,
        "show_record_id": false,
        "batch_size": 0
    }
}

Response OK:

HTTP/1.1 201 Created
{
    "items": [{
        "author": "john doe1_1",
        "title": "Eve for Dummies1_1",
        "created": {
            "$date": 1630022400000
        },
        "modified": {
            "$date": 1598803861786
        }
    },
    {
        "author": "john doe1_2",
        "title": "Eve for Dummies1_2",
        "created": {
            "$date": 1630022400000
        },
        "modified": {
            "$date": 1598803861786
        }
    }]
}

Response Error:

HTTP/1.1 400 Bad Request
HTTP/1.1 401 Unauthorized
HTTP/1.1 404 Not Found

04 Files

files storage and management.

download/properties/hash/list

copy/upload

PUT /api/v2/vault/files/(path: path)

Copy or upload file by path. Copy the file by the path if the URL parameter is ‘dest=<path/to/destination>’.

Copy the file from ‘path’ to ‘dest’.

Request:

None

Response OK:

HTTP/1.1 200 OK
{
    “name”: “<path/to/destination>”
}

Response Error:

HTTP/1.1 400 Bad Request
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
HTTP/1.1 404 Not Found
HTTP/1.1 455 Already Exists
HTTP/1.1 507 Insufficient Storage

Upload the content of the file by path if no URL parameter.

Request:

URL Parameters:

public=<true|false>         # [optional] Whether the file uploaded can be access anonymously. Default is 'false'.
                            #            If true, user can access this file anonymously with script '__anonymous_files__'
                            #            and 'path' parameter.
is_encrypt=<true|false>     # [optional] Whether the content of the file has been encrypted by hive sdk. Default is 'false'.
encrypt_method=<string>     # [optional] The way to encrypt. Default is empty string.

Response OK:

HTTP/1.1 200 OK
{
    “name”: “<path/to/res>”,
    “cid”: “<cid>”  # the cid of ipfs proxy if public=true, else empty.
}

Response Error:

HTTP/1.1 400 Bad Request
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
HTTP/1.1 404 Not Found
HTTP/1.1 507 Insufficient Storage

move

PATCH /api/v2/vault/files/(path: path)

Move the file by path to the file provided by the URL parameter ‘to=<path/to/destination>’

Request:

None

Response OK:

HTTP/1.1 200 OK
{
    “name”: “<path/to/destination>”
}

Response Error:

HTTP/1.1 400 Bad Request
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
HTTP/1.1 404 Not Found
HTTP/1.1 455 Already Exists

delete

DELETE /api/v2/vault/files/(path: path)

Delete the file by path.

Request:

None

Response OK:

HTTP/1.1 204 No Content

Response Error:

HTTP/1.1 400 Bad Request
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
HTTP/1.1 404 Not Found

05 Scripting

The scripting module supports share the data of the vault service for other users.

register script

PUT /api/v2/vault/scripting/(script_name)

Register a new script for the vault data owner by the script name.

Script caller will run the script by name later. The script is treated as the channel for other users to access the owner’s data. This will set up a condition and an executable. The condition is checked and must matches before running the executable. What the executable can do depends on the type of it. For example, the type “find” can query the documents from a collection.

Request:

{
    "condition": {
        "type": "queryHasResult",
        "name": "verify_user_permission",
        "body": {
            "collection": "groups",
            "filter": {
                "_id": "$params.group_id",
                "friends": "$caller_did"
            }
        }
    },
    "executable": {
        "type": "find",
        "name": "find_messages",
        "output": true,
        "body": {
            "collection": "messages",
            "filter": {
                "group_id": "$params.group_id"
            },
            "options": {
                "projection": {
                    "_id": false
                },
                "limit": 100
            }
        }
    },
    "allowAnonymousUser": false,
    "allowAnonymousApp": false
}

Response OK:

HTTP/1.1 200 OK
{
    "find_messages": {
        "acknowledged":true,
        "matched_count":1,
        "modified_count":1,
        "upserted_id":null
    }
}

Response Error:

HTTP/1.1 401 Unauthorized
HTTP/1.1 400 Bad Request
HTTP/1.1 403 Forbidden
HTTP/1.1 507 Insufficient Storage

Condition

There are three types of conditions: ‘and’, ‘or’, ‘queryHasResult’. The ‘and’ and the ‘or’ are for merging other type conditions and can be recursive. ‘queryHasResult’ is for checking whether the document can be found in the collection by a filter. Here is an example for three types:

{
   "condition":{
      "type":"and",
      "name":"verify_user_permission",
      "body":[
         {
            "type":"or",
            "name":"verify_user_permission",
            "body":[
               {
                  "type":"queryHasResult",
                  "name":"user_in_group",
                  "body":{
                     "collection":"groups",
                     "filter":{
                        "_id":"$params.group_id",
                        "friends":"$caller_did"
                     }
                  }
               },
               {
                  "type":"queryHasResult",
                  "name":"user_in_group",
                  "body":{
                     "collection":"groups",
                     "filter":{
                        "_id":"$params.group_id",
                        "friends":"$caller_did"
                     }
                  }
               }
            ]
         },
         {
            "type":"queryHasResult",
            "name":"user_in_group",
            "body":{
               "collection":"groups",
               "filter":{
                  "_id":"$params.group_id",
                  "friends":"$caller_did"
               }
            }
         }
      ]
   }
}

Executable

There are nine types of executables. Here lists all types with the relating examples. For the request params and the response, please check Run Script for how to use them. No response will be provided if the output option sets to false.

Possible executable types are here:

  • aggregated

  • find

  • insert

  • update

  • delete

  • fileUpload

  • fileDownload

  • fileProperties

  • fileHash

get scripts

GET /api/v2/vault/scripting/scripts

Get the scripts which user already registered.

Request:

URL Parameters:

<skip>  # optional, default is 0
<limit> # optional, default is 0 ()
<name>  # the script name.

Response OK:

HTTP/1.1 200 OK
{
    "scripts": [{ # the content of every script.
        "context": {...},
        "executable": {...},
        "allowAnonymousUser": false,
        "allowAnonymousApp": false
    }]
}

Response Error:

HTTP/1.1 401 Unauthorized
HTTP/1.1 400 Bad Request
HTTP/1.1 403 Forbidden
HTTP/1.1 404 Not Found

call script

PATCH /api/v2/vault/scripting/(script_name)

Run the script registered by the owner.

Before running the script, the caller needs to check if matches the script condition. The parameter ‘context’ is also required for tell the scripting service which did and app_did is the data belongs to.

The ‘params’ parameter is used to provide the value which the script requires if exists.

Request:

{
    "context": {
        "target_did": "did:elastos:icXtpDnZRSDrjmD5NQt6TYSphFRqoo2q6n",
        "target_app_did":"appId"
    },
    "params": {
        "group_id": {"$oid": "5f8d9dfe2f4c8b7a6f8ec0f1"}
    }
}

Response OK:

HTTP/1.1 200 OK
{
   "get_groups":{
      "items":[
         {
            "name":"Tuum Tech"
         }
      ]
   }
}

Response Error:

HTTP/1.1 401 Unauthorized
HTTP/1.1 400 Bad Request
HTTP/1.1 404 Not Found
HTTP/1.1 403 Forbidden

call script url

GET /api/v2/vault/scripting/(script_name)/(context_str)/(params)

Run the script registered by the owner by the URL parameters.

This is the same as Run Script.

URL Parameters:

<context_str> # context for running the script. format: <target_did>@<target_app_did>
<params> # params for running the script with json format.

Response OK:

HTTP/1.1 200 OK
{
   "get_groups":{
      "items":[
         {
            "name":"Tuum Tech"
         }
      ]
   }
}

Response Error:

HTTP/1.1 401 Unauthorized
HTTP/1.1 400 Bad Request
HTTP/1.1 404 Not Found
HTTP/1.1 403 Forbidden

unregister script

DELETE /api/v2/vault/scripting/(script_name)

Unregister the script by the script name and the script can not be called anymore.

Request:

None

Response OK:

HTTP/1.1 204 No Content

Response Error:

HTTP/1.1 401 Unauthorized
HTTP/1.1 400 Bad Request
HTTP/1.1 403 Forbidden
HTTP/1.1 404 Not Found

upload file

PUT /api/v2/vault/scripting/stream/(transaction_id)

Upload file by transaction id returned by the running script for the executable type ‘fileUpload’.

Request:

<The bytes content of the file>

Response OK:

HTTP/1.1 200 OK

Response Error:

HTTP/1.1 401 Unauthorized
HTTP/1.1 400 Bad Request
HTTP/1.1 404 Not Found
HTTP/1.1 403 Forbidden
HTTP/1.1 507 Insufficient Storage

download file

06 Backup

The backup module is for backup data to other hive node. The credential is required for the vault service to access the backup service.

get state

GET /api/v2/vault/content

Get the status of the backup processing.

Request:

None

Response OK:

HTTP/1.1 200 OK
{
    "state": "stop", # stop, backup, restore
    "result": "success" # success, failed, process
    "message": "" # any message for the result.
}

Response Error:

HTTP/1.1 401 Unauthorized

backup & restore

POST /api/v2/vault/content

Backup or restore the data of the vault service.

Backup the data to another hive node by the credential if contains URL parameter is to=hive_node.

Request:

{
   "credential":"<credential_string>"
}

Response OK:

HTTP/1.1 201 Created

Response Error:

HTTP/1.1 400 Bad Request
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
HTTP/1.1 507 Insufficient Storage

Restore the data from the other hive node if the URL parameter is from=hive_node.

Request:

{
   "credential":"<credential_string>"
}

Response OK:

HTTP/1.1 201 Created

Response Error:

HTTP/1.1 400 Bad Request
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
HTTP/1.1 507 Insufficient Storage

promote

POST /api/v2/backup/promotion

Promote a backup service to the vault service on backup node.

Request:

None

Response OK:

HTTP/1.1 200 OK

Response Error:

HTTP/1.1 401 Unauthorized
HTTP/1.1 404 Not Found
HTTP/1.1 455 Already Exists
HTTP/1.1 507 Insufficient Storage

07 Payment

The payment module is for upgrading the vault or the backup service.

get version

GET /api/v2/payment/version

Get the version of the payment implementation.

Request:

None

Response OK:

HTTP/1.1 200 OK
{
    "version": "1.0"
}

Response Error:

HTTP/1.1 401 Unauthorized

place order

PUT /api/v2/payment/order

Place an order for getting more storage space.

The vault service MUST be subscribed before placing the order.

Request:

{
   "subscription": <vault | backup>,
   "pricing_name": "Standard"
}

Response OK:

HTTP/1.1 200 OK
{
    "interim_orderid": "<ObjectId str>",  // internal order id on hive node
    "subscription": "vault",
    "pricing_plan": "Standard",
    "paying_did": "did:elastos:iWFAUYhTa35c1f3335iCJvihZHx6q******",
    "payment_amount": 15,  // ELA
    "create_time": 1600073834,
    "expiration_time": 1755161834,
    "receiving_address": "0x60Dcc0f996963644102fC266b39F1116e5******",
    "state": "normal",
    "proof": "<jwt string>"
}

the decoded content of proof is like this:

{
   "header":{
        "typ": "JWT",
        "version": "1.0",
        "alg": "ES256",
   },
   "payload":{
        "ver": "1.0",
        "sub": "Hive Payment",
        "aud": "did:elastos:ixxxx",  // the user who need to make payment
        "iat": 1600073832,
        "iss": "did:elastos:iWFAUYhTa35c1fPe3iCJvihZHx6q*****",  // service did
        "order": {
            "interim_orderid": "<ObjectId str>",  // internal order id on hive node
            "subscription": "vault/backup",
            "pricing_plan": "rookie/advanced",
            "paying_did": "did:elastos:iWFAUYhTa35c1f3335iCJvihZHx6q******",
            "payment_amount": 14,  // ELA
            "create_time": 1600073834,
            "expiration_time": 1755161834,
            "receiving_address": "0x60Dcc0f996963644102fC266b39F1116e*******",
            "state": "normal",
        }
   },
   "signature": "rW6lGLpsGQJ7kojql78rX7p-MnBMBGEcBXYHkw_heisv7eEic574qL-0Immh0f0qFygNHY7RwhL47P*******"
}

Response Error:

HTTP/1.1 400 Bad Request
HTTP/1.1 401 Unauthorized
HTTP/1.1 404 Not Found

settle order

POST /api/v2/payment/order/(order_id)

Notify the payment contract is already done and let hive node upgrade the user vault.

After this, the vault will be upgraded for a specific pricing plan.

Request:

None

Response OK:

HTTP/1.1 200 OK
{
    "receipt_id": “<ObjectId str>”,
    "order_id": 1234,
    "subscription": "vault",
    "pricing_plan": "Standard",
    "payment_amount": "5",  // ELA
    "paid_did": "did:elastos:insTmxdDDuS9wHHfeYD1h5C2onEH******”,
    "create_time": 1600073834,
    "receiving_address": "912ec803b2ce49e4a541068d49******",
    "receipt_proof": "<jwt str>"
}

the decoded content of receipt_proof is like this:

{
    "header":{
        "typ": "JWT",
        "version": "1.0",
        "alg": "ES256"
    },
    "payload":{
        "ver": "1.0",
        "sub": "Hive Recepit",
        "aud": "did:elastos:ixxxx",  // the user who need to make payment
        "iat": 1600073834,
        "iss": "did:elastos:iWFAUYhTa35c1fPe3iCJvihZHx6******",  // service did
        "receipt":{
            "receipt_id": "<ObjectId str>",
            "order_id": 445,
            "subscription": "vault",
            "pricing_plan": "Standard",
            "paid_did": "did:elastos:iWFAUYhTa35c1f3335iCJvihZHx6******",  // the did who paid for the order.
            "payment_amount": 15,  // ELA
            "create_time": 1600073834,
            "receiving_address": "0x60Dcc0f996963644102fC266b39F1116******"
        }
    },
    "signature": "rW6lGLpsGQJ7kojql78rX7p-MnBMBGEcBXYHkw_heisv7eEic574qL-0Immh0f0qFygNHY7RwhL47******"
}

Response Error:

HTTP/1.1 400 Bad Request
HTTP/1.1 401 Unauthorized
HTTP/1.1 404 Not Found

get orders

GET /api/v2/payment/order

Get the orders for the vault or the backup service, or by specific order id.

URL Parameters:

subscription: <vault | backup | all>    # optional
order_id: <order_id>                    # optional

Response OK:

HTTP/1.1 200 OK
{
   "orders": [{
        "order_id": 1234,
        "subscription": "vault",
        "pricing_plan": "Standard",
        "paying_did": "did:elastos:iWFAUYhTa35c1f3335iCJvihZHx6q******",
        "payment_amount": "5",  // ELA
        "create_time": 1600073834,
        "expiration_time": 1755161834,
        "receiving_address": "912ec803b2ce49e4a541068d49******",
        "state": "paid",
        "proof": "<jwt str>"
    }]
}

Response Error:

HTTP/1.1 400 Bad Request
HTTP/1.1 401 Unauthorized
HTTP/1.1 404 Not Found

get receipts

GET /api/v2/payment/receipt

Get the receipt information by the order id.

URL Parameters:

order_id: <order_id>  # optional

Response OK:

HTTP/1.1 200 OK
{
    "receipts": [{
        "receipt_id": “<ObjectId str>”,
        "order_id": 1234,
        "subscription": "vault",
        "pricing_plan": "Standard",
        "payment_amount": "5",  // ELA
        "paid_did": "did:elastos:insTmxdDDuS9wHHfeYD1h5C2onEH******”,
        "create_time": 1600073834,
        "receiving_address": "912ec803b2ce49e4a541068d49******",
        "receipt_proof": "<jwt str>"
    }]
}

Response Error:

HTTP/1.1 400 Bad Request
HTTP/1.1 401 Unauthorized
HTTP/1.1 404 Not Found

08 About

Show some information of the hive node. No authentication is required.

get version

GET /api/v2/node/version

Get the version of hive node. No authentication is required.

Request:

None

Response OK:

HTTP/1.1 200 OK
{
    "major": 1,
    "minor": 0,
    "patch": 0
}

get commit id

GET /api/v2/node/commit_id

Get the commit ID of hive node. No authentication is required.

Request:

None

Response OK:

HTTP/1.1 200 OK
{
    "commit_id": "<commit_id>"
}

get node information

GET /api/v2/node/info

Get the information of this hive node.

Request:

None

Response OK:

HTTP/1.1 200 OK
{
    "service_did": <str>,
    "owner_did": <str>,
    "ownership_presentation": <str>,
    "name": <str>,
    "email": <str>,
    "description": <str>,
    "version": <str>,
    "last_commit_id": <str>,
    "user_count": <int>,
    "vault_count": <int>,
    "backup_count": <int>,
    "latest_access_time": <int>,
    "memory_used": <int>,
    "memory_total": <int>,
    "storage_used": <int>,
    "storage_total": <int>
}

Response Error:

HTTP/1.1 400 Bad Request
HTTP/1.1 401 Unauthorized

09 Provider

The management for the hive node owner or the vault owner.

get vaults

GET /api/v2/provider/vaults

Get all vault information in this hive node.

Request:

None

Response OK:

HTTP/1.1 200 OK
{
    "vaults": [{
        "pricing_using": <pricing name|str>,
        "max_storage": <int>,
        "file_use_storage": <int>,
        "db_use_storage": <int>,
        "user_did": <str>,
        "access_count": <int>,
        "access_amount": <int>,
        "access_last_time": <int>
    }]
}

Response Error:

HTTP/1.1 400 Bad Request
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
HTTP/1.1 404 Not Found

get backups

GET /api/v2/provider/backups

Get all backup information in this hive node.

Request:

None

Response OK:

HTTP/1.1 200 OK
{
    "backups": [{
        "pricing_using": <pricing name|str>,
        "max_storage": <int>,
        "use_storage": <int>,
        "user_did": <user did|str>,
    }]
}

Response Error:

HTTP/1.1 400 Bad Request
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
HTTP/1.1 404 Not Found

get payments

GET /api/v2/provider/filled_orders

Get all payment information in this hive node.

Request:

None

Response OK:

HTTP/1.1 200 OK
{
    "orders": [{
        "receipt_id": “<ObjectId str>”,
        "order_id": 1234,
        "subscription": "vault",
        "pricing_plan": "Standard",
        "payment_amount": "5",  // ELA
        "paid_did": "did:elastos:insTmxdDDuS9wHHfeYD1h5C2onEH******”,
        "create_time": 1600073834,
        "receiving_address": "912ec803b2ce49e4a541068d49******",
        "proof": "<jwt str>"
    }]
}

Response Error:

HTTP/1.1 400 Bad Request
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
HTTP/1.1 404 Not Found

Appendix A: Error Response

When failed with API calling as some error happened in the hive node, the error response will return, such as HTTP/1.1 400 Bad Request.

The body of the error response should contain the following format content which will help caller debug the errors.

{
    “error”: {
        “message”: “the specific error description”, // [mandatory]
        “internal_code”:  <number> // [optional],
        ... //other customized items if it's necessary to report more information. [optional]
    }
}

400 Bad Request

Internal code list:

  • 1, invalid parameter

  • 2, backup is in progress

  • 3, eladid.so error

401 Unauthorized

No internal code defined

403 Forbidden

Internal code list:

  • 1, vault frozen

404 Not Found

Internal code list:

  • 1, vault not found

  • 2, backup service not found

  • 3, script not found

  • 4, collection not found

  • 5, pricing plan not found

  • 6, file not found

  • 7, order not found

  • 8, receipt not found

  • 9, application not found

455 Already Exists

No internal code defined

500 Internal Server Error

No internal code defined

501 Not Implemented Error

No internal code defined

507 Insufficient Storage

No internal code defined

Appendix B: Collections

auth_register

This common collection is for sign-in and auth.

{
    "_id": ObjectId,
    "appInstanceDid": <str>,
    "userDid": <str>,
    "nonce": <for generate token: str>,
    "nonce_expired": <int>,
    "appDid": <str>,
    "token": <str>,
    "token_expired": <int>
}

application

The applications belong to user DID

{
    "_id": ObjectId,
    "user_did": <str>,
    "app_did": <str>,
    "database_name": <str>,
    "state": "normal",
    "created": <timestamp: int, seconds>,
    "modified": <timestamp: int, seconds>
}

vault_service

This common collection keeps the information for the vault.

{
    "_id": ObjectId,
    "did": <user_did: str>,
    "max_storage": <int>,
    "file_use_storage": <int>,
    "db_use_storage": <int>,
    "start_time": <timestamp: float>,
    "end_time": <timestamp, -1 means no end time: float>,
    "modify_time": <timestamp: float>,
    "state": <vault status: str>,
    "pricing_using": <pricing name: str>
}

vault_order

This common collection keeps the information for the payment order.

{
    "_id": ObjectId,
    "user_did": <str>,
    "subscription": <"vault", "backup": str>,
    "pricing_name": <pricing name: str>,
    "ela_amount": <float>,
    "ela_address": <str>,
    "proof": <str>,
    "status": <str>,
    "created": <timestamp: float>,
    "modified": <timestamp: float>
}

vault_receipt

This common collection keeps the information for the payment receipt.

{
    "_id": ObjectId,
    "user_did": <str>,
    "order_id": <str>,
    "transaction_id": <str>,
    "paid_did": <str>,
    "proof": <str>,
    "status": <str>,
    "created": <timestamp: float>,
    "modified": <timestamp: float>
}

ipfs_backup_client

This common collection keeps the backup information in the vault node.

{
    "_id": ObjectId,
    "user_did": <str>,
    "type": "hive_node",
    "action": <"backup", "restore": str>,
    "state": <str>,
    "state_msg": <str>,
    "target_host": <str>,
    "target_did": <str>,
    "target_token": <str>,
    "created": <timestamp: float>,
    "modified": <timestamp: float>
}

ipfs_cid_ref

This common collection keeps the IPFS CID reference count in the vault or backup node.

{
    "_id": ObjectId,
    "cid": <str>,
    "count": <int>,
    "created": <timestamp: float>,
    "modified": <timestamp: float>
}

ipfs_backup_server

This common collection keeps the backup information in the backup node.

{
    "_id": ObjectId,
    "user_did": <str>,
    "backup_using": <pricing name: str>,
    "max_storage": <int>,
    "use_storage": <int>,
    "start_time": <timestamp: float>,
    "end_time": <timestamp, -1 means no end time: float>,
    "created": <timestamp: float>,
    "modified": <timestamp: float>,
    "req_action": <"backup", "restore": str>,
    "req_cid": <str>,
    "req_sha256": <str>,
    "req_size": <int>,
    "req_state": <str>,
    "req_state_msg": <str>
}

database_metadata

This user collection keeps the metadata info. of the user collections.

{
    "_id": ObjectId,
    "user_did": <str>,
    "app_did": <str>,
    "name": <str>,
    "is_encrypt": <bool>,
    "encrypt_method": <str>,
    "created": <timestamp: float>,
    "modified": <timestamp: float>
}

ipfs_files

This user collection keeps the metadata of the files.

{
    "_id": ObjectId,
    "user_did": <str>,
    "app_did": <str>,
    "path": <file relative path: str>,
    "sha256": <str>,
    "is_file": <bool>
    "size": <int>,
    "ipfs_cid": <int>,
    "is_encrypt": <bool>,
    "encrypt_method": <str>,
    "created": <timestamp: float>,
    "modified": <timestamp: float>
}

anonymous_files

This user collection keeps the files which can be accessed anonymously.

{
    "_id": ObjectId,
    "user_did": <str>,
    "app_did": <str>,
    "name": <str>,
    "cid": <int>,
    "created": <timestamp: float>,
    "modified": <timestamp: float>
}

scripts

This user collection keeps the scripts from scripting module.

{
    "_id": ObjectId,
    "name": <script name: str>,
    "executable": <executable definition: dict>,
    "condition": <condition definition: dict>,
    "allowAnonymousUser": <bool>,
    "allowAnonymousApp": <bool>
}

scripts_temptx

This user collection keeps the transaction information for scripts.

{
    "_id": ObjectId,
    "document": {
        "file_name": <file relative path: str>,
        "fileapi_type": <"upload", "download": str>
    },
    "anonymous": <bool>,
    "created": <timestamp: float>,
    "modified": <timestamp: float>
}