Installation and usage of the platform
REST API: confidential data exchange and obtaining of information about confidential data groups¶
Learn more about confidential data exchange and access groups in the article Confidential data exchange.
Use the Privacy
group methods to implement these functions using the REST API.
Privacy
group methods authorization¶
POST /privacy/sendData¶
The method is designed to send sensitive data (available only to the members of the access group defined for this data) to the blockchain.
Note
Use the POST /privacy/sendLargeData method to send data larger than 20 MB.
The POST /privacy/sendData method request must contain the following information:
sender
– blockchain address from which the data should be sent (corresponds to the value of theprivacy.owner-address
parameter in the configuration file of the node);password
– password to access the private key in the node keystore;policyId
– identifier of a group that will have access to the data to be forwarded;info
– information about data being sent:filename
– name of a file,size
– file size,timestamp
– data timestamp,author
– the email of the data author,comment
– optional comment to the data.
data
– string containing data in base64 format;hash
– data sha256-hash in base58 format;broadcast
– iftrue
is passed, the created PolicyDataHash transaction is sent to the blockchain, iffalse
is passed, the transaction and Privacy Inventory are not sent; see below for details.
Note
When transferring files through Amazon S3/Minio, the comment
, author
, filename
fields must have ascii characters. This is the AWS Java SDK limitation.
Sending the request will generate a 114 PolicyDataHash transaction, which will send a hash of sensitive data to the blockchain.
broadcast
parameter¶
To reduce the probability of data delivery errors, it is recommended to set the broadcast
parameter to false
if after sending data using sendData API method an atomic transaction which contains a CreatePolicy and a PolicyDataHash transactions is sent.
Examples of a query and a response:
POST /privacy/sendDataV2¶
The POST /privacy/sendDataV2 method is similar to the POST /privacy/sendData method but allows you to attach a file in the Swagger window without having to convert it to base64 format. The method provides the ability to stream data. The Data
field is missing in this version of the method.
Note
Use the POST /privacy/sendLargeData method to send data larger than 20 MB.
Note
When transferring files through Amazon S3/Minio, the comment
, author
, filename
fields must have ascii characters. This is the AWS Java SDK limitation.
Examples of a query and a response:
POST /privacy/sendLargeData¶
The POST /privacy/sendLargeData method is similar to the POST /privacy/sendDataV2 method, but is used to send data of at least 20 MB in size.
Note
Use the POST /privacy/sendData and POST /privacy/sendDataV2 methods to send data less than 20 MB.
You can configure the backpressure on incoming data chunks in the node configuration file in the node.privacy.service section: set the maximum size for the buffer in the memory (the default is 100 MB).
Note
When transferring files through Amazon S3/Minio, the comment
, author
, filename
fields must have ascii characters. This is the AWS Java SDK limitation.
Examples of a query and a response:
GET /privacy/{policy-id}/recipients¶
The method is designed to get the addresses of all members recorded in group {policy-id}
.
The response of the method returns an array of strings with the addresses of the members of the access group.
Response example:
GET /privacy/{policy-id}/owners¶
The method is designed to get the addresses of the owners of access group {policy-id}
.
The response of the method returns an array of strings with the addresses of the owners of the access group.
Response example:
GET /privacy/{policy-id}/hashes¶
The method is designed to get an array of identification hashes of data bound to the {policy-id}
access group.
The response of the method returns an array of strings with the identity hashes of the access group data.
Response example:
GET /privacy/{policyId}/getData/{policyItemHash}¶
The method is designed to retrieve a packet of confidential data of {policyId}
access group by the identification hash {policyItemHash}
.
The response of the method returns the hash sum of the confidential data.
Response example:
GET /privacy/{policyId}/getLargeData/{policyItemHash}¶
The method is designed to retrieve a packet of confidential data of {policyId}
access group by the identification hash {policyItemHash}
.
The method returns data stream, which allows the user to download a data file of unlimited size.
GET /privacy/{policyId}/getInfo/{policyItemHash}¶
The method is designed to retrieve the confidential data packet metadata of {policyId}
access group by the identification hash {policyItemHash}
.
The method response returns the following data:
sender
– an address of confidential data sender;policy_id
– a confidential data group identifier;type
– type of confidential data (file
);info
– file data array:filename
– name of a file;size
– file size;timestamp
– the file placement Unix Timestamp (in milliseconds);author
– file author;comment
– optional comment to the file;
hash
– confidential data identifying hash.
Response example:
POST /privacy/forceSync¶
The method is designed to force a packet of confidential data. It is used if a transaction with confidential data for an access group is present in the blockchain, but for some reason this data was not written to the node’s confidential data repository. In this case, the method allows to forcibly download the missing data. The method synchronizes data across all sensitive data access groups.
The response includes the following data:
sender
– address of the node participating in the access group that sends the request;policy
– a confidential data group identifier;source
– address of the node from which the missing data should be downloaded. In case the node is unknown, set the parameter tonull
or leave the field empty: in this case the file will be downloaded from the storage of the first node in the access group list.
Method response contains a result
field with data retrieval result and a message
field with possible error text. In case of successful reception, success
is returned, confidential data is written to node storage.
If an error occurs, error
is returned, the message
field contains a description of the error.
Examples of a query and a response:
GET /privacy/forceSync/{policyId}¶
The method is similar to the POST /privacy/forceSync method with the difference that it synchronizes data by the specified privacy access group (policyId).
POST /privacy/getInfos¶
The method is designed to obtain an array of confidential data metadata by access group identifier and identification hash.
The response includes the following data:
policiesDataHashes
– an array of data with two elements for each individual access group:policy_id
– a confidential data group identifier,datahashes
– an array of sensitive data hashes to get metadata for each of them.
The method response returns an array of data for each individual hash of sensitive data, similar to the response of the GET /privacy/{policyId}/getInfo/{policyItemHash}
method.
Examples of a query and a response: