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 |
Sign in with app instance DID |
|
Get the access token. |
||
02 Subscription |
Vault Subscribe |
|
Vault Unsubscribe |
||
Get Vault Info. |
||
Get App Stats |
||
Activate&Deactivate |
||
Backup Subscribe |
||
Backup Unsubscribe |
||
Get Backup Info. |
||
Get Vault Pricing Plans. |
||
03 Database |
Get collections |
|
Create the collection |
||
Delete the collection |
||
Insert&count the documents |
||
Update the documents |
||
Delete the documents |
||
Find the documents |
||
Query the documents |
||
04 Files |
Copy/upload |
|
Move |
||
Delete |
||
05 Scripting |
Register |
|
Get Scripts |
||
Run Script |
||
GET /api/v2/vault/scripting/(script_name)/(context_str)/(params) |
Run Script URL |
|
Unregister |
||
Upload File |
||
06 Backup |
Get the State |
|
Backup & Restore |
||
Promote |
||
07 Payment |
Get Version |
|
Place Order |
||
Settle Order |
||
Get Orders |
||
Get the Receipt |
||
08 About |
Get the Version |
|
Get the Commit ID |
||
Get Node Information |
||
09 Provider |
Get Vaults |
|
Get Backups |
||
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
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>
}