API
Tributech provides two REST APIs:
- Data-API (data-api.[node name].dataspace-node.com)
- Trust-API (trust-api.[node name].dataspace-node.com)
The image below shows you how the APIs are integrated.
In short, the Data-API is used for values whereas the Trust-API is used for proofs. Proofs are required in order to verify the validity and consistency of data. The Trust-API also offers some endpoints which integrate the Data-API.
Data-API Specifications
Data-API calls and specifications can be found at data-api.[node name].dataspace-node.com
The page gives an overview of the available calls and actions.
Please note that all timestamps need to be provided in microseconds!
Trust-API Specifications
Trust-API calls and specifications can be found at trust-api.[node name].dataspace-node.com
The page gives an overview of the available calls and actions.
Please note that all timestamps need to be provided in microseconds!
Clients
For both APIs, the "OpenAPI" (Swagger) specifications can be found in the top left, which can be used to generate a clients for the APIs.
If C# is the programming language of choice, our already prepared clients can be found here: https://github.com/tributech-solutions/tributech-dsk-api-clients
Use Case Examples
The following use cases should help to understand when to use which API.
Store values
Unless the proofs are created directly on an external device (e.g. Tributech Agent Edge), the Trust-API should be used to store values and automatically create and persist the respective proofs. The /value and /values HTTP POST endpoints of the Trust API can be used to do so.
If however the proofs are created separately, then the /value and /values HTTP POST endpoints of the Data-API can be used to only store values - the proofs are then stored manually through the /proof and /proofs HTTP POST endpoints of the Trust-API.
Get values
The Data-API provides various /values HTTP GET endpoints to fetch values.
Values can also be retrieved together with the respective proof through the /proofvalues HTTP GET endpoint of the Trust-API.
Note: The Data-API also handles the syncing of values between Tributech Nodes (as far as approved through the parties). The status for this syncing process is available through the Status endpoints of the Data-API.
Store proofs
The Trust-API /proof and /proofs HTTP POST endpoints can be used to store proofs.
Note: Each proof is stored tamperproof within the Distributed Ledger (Blockchain) across the Tributech network. Consequently, each proof is assigned a unique TransactionId - which can be used to fetch the proof from the Ledger. This endpoint to retrieve the proof from the Blockchain is called ProofLocation and can be accessed through the available endpoints in the Data-API.
Get proofs
Proofs can be fetched through the /proof HTTP GET endpoint of the Trust-API. A proof can also be retrieved together with the assigned values through the /proofvalues HTTP GET endpoint of the Trust-API.
Validate proofs
A proof can be validated through the /validate/proof HTTP POST endpoint of the Trust-API.
Please note that all timestamps need to be provided in microseconds!
Step-by-Step Example: Get a Double Value with its ValueMetadataId
Note that this requires double values to be provided on the Data-API. If the values originate from an external data provider, they are available in the Dataset subscriptions. Otherwise check out the Provide Data documentation, to provide the values yourself.
- On your node dashboard: Access your profile on the top right and head to "Administration->API Keys" to find your Data-API client secret. Copy it.
- Head to the Data-API specification page (data-api.[node name].dataspace-node.com).
- Click the "Authorize" button and paste the Data-API client secret.
- Scroll down and select the "GET/values/double/{valueMetadataId}" endpoint.
- Click "Try it out" and replace the ValueMetadataId parameter with your own.
- In the response message, you should now be able to find the double value.
