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 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 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>
}

Hive Node API Documentation

Summary

01 Auth

sign in

auth

02 Subscription

vault subscribe

vault unsubscribe

get vault info.

get app stats

activate & deactivate

backup subscribe

backup unsubscribe

get backup info.

get pricing plans

03 Database

get collections

create collection

delete collection

insert or count documents

update documents

delete documents

find documents

query documents

04 Files

download/properties/hash/list

copy/upload

move

delete

05 Scripting

register script

get scripts

call script

call script url

unregister script

upload file

download file

06 Backup

get state

backup & restore

promote

07 Payment

get version

place order

settle order

get orders

get receipts

08 About

get version

get commit id

get node information

09 Provider

get vaults

get backups

get payments

Appendix A: Error Response

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

455 Already Exists

500 Internal Server Error

501 Not Implemented Error

507 Insufficient Storage

Appendix B: Collections

auth_register

application

vault_service

vault_order

vault_receipt

ipfs_backup_client

ipfs_cid_ref

ipfs_backup_server

database_metadata

ipfs_files

anonymous_files

scripts

scripts_temptx