Track¶
Track API is used to create, manage, and follow life cycle of digital assets on the blockchain. An asset is a digital representation of a real asset in the physical world. Through this API tracking the whole state changes of every asset can be implemented in an easy way, taking advantage of the inherit benefits from blockchain.
API Specification¶
An abstraction API with all the asset functionalities.
Asset¶
An asset is a digital representation of a real asset in the physical world. An asset records every single state or data change (f.e. the update of metadata, the transfer of ownership, etc.) This allow us to track the whole transactions since its creation in an inmutable and transparent way.
Every asset has the following structure:
assetid:<string>Unique identifier of the assetdata:<json>JSON of inmutable data. Can have as many fields as required by the use casemetadata:<json>JSON of mutable data. Can have as many fields as required by the use casetimestamp:<string>UNIX date of asset creationuserOwner:<string>Owner of the assethash:<string>Hash of the asset
Sample structure (Click to expand)
{
"assetid": "exampleAsset",
"data": {
"id":"A2839RP",
"version":"1"
},
"metadata": {
"color": "red"
"position": { "x": "53", "y": "22"}
},
"timestamp": 1558009289,
"userOwner": "test:telefonicaMSP",
"hash": "oCZygxQBp5HBVm+SSUCCrgJfV3+CeghOzV9m+UxDsY8=",
}
Authorised assets¶
There are two types of assets: owned assets and authorised assets. These last ones, the authorised assets are assets created by other users that have granted you access allowing you to consult and update it.
In order to interact with both assets in some functions it is necessary to set a flag formely known as isAuthorised. In order to interact with authorised, only it is necessary to set the isAuthorised flag to true as a query parameter in the URL (...?isAuthorised=true) as it is shown in the examples below:
- GET -
/asset/{assetId}?isAuthorised=boolean - GET -
/asset/{assetId}/transactions?isAuthorised=boolean - POST -
/asset/{assetId}/transactions/range?isAuthorised=boolean - GET -
/assets?isAuthorised=boolean - POST -
/asset/{assetId}/update?isAuthorised=boolean - POST -
/asset/{assetId}/batch/array?isAuthorised=boolean - POST -
/asset/{assetId}/batch/range?isAuthorised=boolean - POST -
/asset/{assetId}/batch/updateArray?isAuthorised=boolean - POST -
/asset/{assetId}/batch/updateRange?isAuthorised=boolean - POST -
/asset/{assetId}/evidence?isAuthorised=boolean - POST -
/asset/{assetId}/getEvidence?isAuthorised=boolean - GET -
/asset/{assetId}/getEvidences?isAuthorised=boolean
To manage your own assets you must set the parameter to false (...?isAuthorised=false).
API Methods¶
Asset methods (Click to expand)
POST - /asset/create¶
Ceate a digital asset.
Input
assetid:<string>Unique identifier of the asset.data:<json>JSON of inmutable data. It can have as many field as required.metadata:<json>JSON of mutable data. It can have as many field as required.metadata:<bool>Boolean value to set if it is a batch asset or not.
Sample structure (Click to expand)
{
"assetid": "",
"data": {
"id":"A2839RP",
"version":"1"
},
"metadata" : {
"color": "red",
"position": { "x": 23.34, "y": -24.22}
}
}
Output
asset:<json>
Sample structure (Click to expand)
{
"assetid": "exampleAsset",
"data": {
"id":"A2839RP",
"version":"1"
},
"metadata": {
"color": "red"
"position": { "x": "53", "y": "22"}
},
"timestamp": 1558009289,
"userOwner": "test:telefonicaMSP",
"hash": "oCZygxQBp5HBVm+SSUCCrgJfV3+CeghOzV9m+UxDsY8=",
}
GET - /asset/{assetId}?isAuthorised=boolean¶
Get the asset identified by assetId.
Input
assetid:<string>Unique identifier of the asset.isAuthorised:<boolean>Flag to get own or authorised assets.
(*) Please navigate to the following section for isAuthorised query param details.
Output
asset:<json>
Sample structure (Click to expand)
{
"assetid": "exampleAsset",
"data": {
"id":"A2839RP",
"version":"1"
},
"metadata": {
"color": "red"
"position": { "x": "53", "y": "22"}
},
"timestamp": 1558009289,
"userOwner": "test:telefonicaMSP",
"hash": "oCZygxQBp5HBVm+SSUCCrgJfV3+CeghOzV9m+UxDsY8=",
}
POST /asset/{assetId}/update?isAuthorised=boolean¶
Updates the mutable (“metadata”) of an asset.
Input
assetid:<string>Unique identifier of the asset.isAuthorised:<boolean>Flag to update own (false) or authorised (true) assets.metadata:<json>JSON of mutable data. It can have as many field as required.
(*) Please navigate to the following section for isAuthorised query param details.
Sample structure (Click to expand)
{
"metadata": {
"color": "blue",
"position": { "x": 98.35, "y": -12.32}
}
}
Output
asset:<json>
Sample structure (Click to expand)
{
"output": {
"assetId": "test1",
"data": {
"color": "yellow",
"size": "big"
},
"metadata": {
"color": "blue",
"position": {
"x": 98.35,
"y": -12.32
}
},
"timestamp": 1647953653,
"userOwner": "did:vtn:trustid:ed770703f65656e5b689a047d1cee645b7ad119610a1d31a63f5be0e45c6e0d9",
"hash": "F5SzRyp4ELhbtcDEsPm8a+2XjyI5w4uoLkAb5yO9C0E="
}
}
GET - /asset/{assetId}/transactions?isAuthorised=boolean¶
Get all transactions for the whole lifecycle of the asset.
Input
assetid:<string>Unique identifier of the asset.isAuthorised:<boolean>Flag to get own or authorised assets.
(*) Please navigate to the following section for isAuthorised query param details.
Output
asset:<json>A list of all transactions.
Sample structure (Click to expand)
{
"output": {
"assetId": "test1",
"data": {
"color": "yellow",
"size": "big"
},
"transactions": [
{
"metadata": {
"color": "red",
"size": "medium"
},
"timestamp": 1647953221,
"userOwner": "did:vtn:trustid:ed770703f65656e5b689a047d1cee645b7ad119610a1d31a63f5be0e45c6e0d9",
"hash": "a20Reot68bbYEap+RfN4EmtEbrKoE0UO9rgn205jln0="
},
{
"metadata": {
"color": "blue",
"size": "big"
},
"timestamp": 1647951890,
"userOwner": "did:vtn:trustid:ed770703f65656e5b689a047d1cee645b7ad119610a1d31a63f5be0e45c6e0d9",
"hash": "RB/vC1wSwS2hhbttvmtMehWROqmcwlPL9+tkdODLVGI="
}
]
}
}
POST - /asset/{assetId}/transactions/range?isAuthorised=boolean¶
Get all transactions within a range for the whole lifecycle of the asset.
Input
assetid:<string>Unique identifier of the asset.isAuthorised:<boolean>Flag to get own or authorised assets.init:<string>Transactions low limit.end:<string>Transactions upper limit.
(*) Please navigate to the following section for isAuthorised query param details.
Sample structure (Click to expand)
{
"init": "0",
"end": "1575975331"
}
Output
asset:<json>A list of all transactions.
Sample structure (Click to expand)
{
"output": {
"assetId": "test1",
"data": {
"color": "yellow",
"size": "big"
},
"transactions": [
{
"metadata": {
"color": "red",
"size": "medium"
},
"timestamp": 1647953221,
"userOwner": "did:vtn:trustid:ed770703f65656e5b689a047d1cee645b7ad119610a1d31a63f5be0e45c6e0d9",
"hash": "a20Reot68bbYEap+RfN4EmtEbrKoE0UO9rgn205jln0="
},
{
"metadata": {
"color": "blue",
"size": "big"
},
"timestamp": 1647951890,
"userOwner": "did:vtn:trustid:ed770703f65656e5b689a047d1cee645b7ad119610a1d31a63f5be0e45c6e0d9",
"hash": "RB/vC1wSwS2hhbttvmtMehWROqmcwlPL9+tkdODLVGI="
}
]
}
}
POST - /asset/{assetId}/transfer¶
Transfer the ownership of the asset. The user has to be the owner of the asset.
Input
assetid:<string>Unique identifier of the asset.destinationId:<string>The destination owner.
Sample structure (Click to expand)
{
"destinationId": "bteam",
}
Output
asset:<json>
Sample structure (Click to expand)
{
"assetid": "exampleAsset",
"data": {
"id":"A2839RP",
"version":"1"
},
"metadata": {
"color": "red"
"position": { "x": "53", "y": "22"}
},
"timestamp": 1558009289,
"userOwner": "bteam",
"hash": "oCZygxQBp5HBVm+SSUCCrgJfV3+CeghOzV9m+UxDsY8=",
}
POST - /asset/{assetId}/rules¶
Add rules to monitor asset parameters.
Input
assetId:<string>Unique identifier of the asset.rules:<json>JSON of rules. It can have at least two fields: value & range, to specify a constant value or range of values that has to accomplish a parameter. Every rule (value, range) can contain as many conditions for different parameters as necessary. However it’s noted that a use of quite many conditions affects the performance of the asset udpates.
Sample structure (Click to expand)
{
"rules": {
"value": [
{
"param": "a",
"value": "b"
},
{
"param": "aa",
"value": "bb"
}
],
"range": [
{
"param": "b",
"min": 0,
"max": 100
}
]
}
}
Output
rules:<json>
Sample structure (Click to expand)
{
{
"rules": {
"value": [
{
"param": "a",
"value": "b"
},
{
"param": "aa",
"value": "bb"
}
],
"range": [
{
"param": "b",
"min": 0,
"max": 100
}
]
}
}
POST - /asset/{assetId}/authorise¶
Authorise user access for an asset. Only the asset owner can do this.
Input
assetId:<string>Unique identifier of the asset.userId:<string>The authorised user.
Sample structure (Click to expand)
{
"userId": "did:bteam"
}
Output
asset:<json>
Sample structure (Click to expand)
{
"output": {
"message": "Successfully authorised user did:bteam for asset XXXXX",
}
}
POST - /asset/{assetId}/unauthorise¶
Unauthorise user access for an asset. Only the asset owner can do this.
Input
assetId:<string>Unique identifier of the asset.userId:<string>The unauthorised user.
Sample structure (Click to expand)
{
"userId": "did:bteam"
}
Output
asset:<json>
Sample structure (Click to expand)
{
"output": {
"message": "Successfully unauthorised user did:bteam for asset XXXXX",
}
}
GET - /assets?isAuthorised=boolean¶
Get all assets for user
Input
isAuthorised:<bool>Flag to get own or authorised assets.
(*) Please navigate to the following section for isAuthorised query param details.
Output
assetList:<json>
Sample structure (Click to expand)
{
"output": [
"exampleAsset1",
"exampleAsset2",
"exampleAsset3"
]
}
POST - /assets/create¶
Creates assets from file
Input
fileInput:<string>File from which the asset will be generated.
Output
output:<json>
Sample structure (Click to expand)
{
"output": [
{
"message": "The asset with assetId x has been created successfully"
}
]
}
POST - /assets/update¶
Updates assets from file
Input
fileInput:<string>File from which the asset will be updated.
Output
output:<string>
Sample structure (Click to expand)
{
"output": [
{
"message": "The asset with assetId x has been updated successfully"
}
]
}
POST - /asset/{assetId}/batch/array?isAuthorised=boolean¶
Creates batch info for an specific asset. This is a list with the IDs of the assets that will belong to the batch.
Input
assetid:<string>Unique identifier of the asset.isAuthorised:<boolean>Flag to get own or authorised assets.batchInfo:<json>Array that will represent the list of the IDs of the assets that will belong to the batch.
Output
output:<string>
Sample structure (Click to expand)
{
"output": "Batch stored successfully"
}
POST - /asset/{assetId}/batch/range?isAuthorised=boolean¶
Creates batch info for an specific asset. This is a range of the IDs of the assets that will belong to the batch.
Input
assetid:<string>Unique identifier of the asset.isAuthorised:<boolean>Flag to get own or authorised assets.init:<string>Range of the IDs of the assets that will belong to the batch.end:<string>Range of the IDs of the assets that will belong to the batch.
Output
output:<string>
Sample structure (Click to expand)
{
"output": "Batch stored successfully"
}
POST - /asset/{assetId}/batch/updateArray?isAuthorised=boolean¶
Update batch info for an specific asset. This is a list with the IDs of the assets that will be added to the batch.
Input
assetid:<string>Unique identifier of the asset.isAuthorised:<boolean>Flag to get own or authorised assets.batchArray:<json>Array that will represent the list of the IDs of the assets that will be added to the batch.
Output
output:<string>
Sample structure (Click to expand)
{
"output": "Batch stored successfully"
}
POST - /asset/{assetId}/batch/updateRange?isAuthorised=boolean¶
Update batch info for an specific asset. This is a range of the IDs of the assets that will belong to the batch.
Input
assetid:<string>Unique identifier of the asset.isAuthorised:<boolean>Flag to get own or authorised assets.init:<string>Range of the IDs of the assets that will belong to the batch.end:<string>Range of the IDs of the assets that will belong to the batch.
Output
output:<string>
Sample structure (Click to expand)
{
"output": "Batch stored successfully"
}
POST - /asset/{assetId}/admin/create¶
Creates an admin user that is going to be able to authorise other users. Only the asset owner can do this. There can be more than one admin user and the admin can be admin from different assets of different owners.
Input
assetId:<string>Unique identifier of the asset.userId:<string>The user that is going to manage the asset access.
Sample structure (Click to expand)
{
"userId": "did:bteam"
}
Output
output:<string>
Sample structure (Click to expand)
{
"output": "Authorisation has been sucessfully done for asset: example1 and user: did:vtn:trustid:bob"
}
POST - /asset/{assetId}/admin/delete¶
Delete an admin user that is not going to be able to authorise other users. Only the asset owner can do this.
Input
assetId:<string>Unique identifier of the asset.userId:<string>The user that is going to manage the asset access.
Sample structure (Click to expand)
{
"userId": "did:bteam"
}
Output
output:<string>
Sample structure (Click to expand)
{
"output": "Authorisation has been sucessfully done for asset: example1 and user: did:vtn:trustid:bob"
}
POST - /asset/{assetId}/admin/authorise¶
Authorise user access for an asset. Only the asset admin can do this.
Input
assetId:<string>Unique identifier of the asset.userId:<string>The authorised user.ownerId:<string>The asset’s owner.
Sample structure (Click to expand)
{
"userId": "did:bteam",
"ownerId": "did:bteam"
}
Output
output:<string>
Sample structure (Click to expand)
{
"output": "Authorisation has been sucessfully done for asset: example1 and user: did:vtn:trustid:bob"
}
POST - /asset/{assetId}/admin/unauthorise¶
Unauthorise user access for an asset. Only the asset owner can do this.
Input
assetId:<string>Unique identifier of the asset.userId:<string>The unauthorised user.ownerId:<string>The asset’s owner.
Sample structure (Click to expand)
{
"userId": "did:bteam",
"ownerId": "did:bteam"
}
Output
output:<json>
Sample structure (Click to expand)
{
"output": "Authorisation has been sucessfully done for asset: example1 and user: did:vtn:trustid:bob"
}
POST - /asset/{assetId}/evidence?isAuthorised=boolean?networkId=int¶
Create an asset evidence in a public network.
Input
assetId:<string>Asset identifier.isAuthorised:<boolean>Flag to get own or authorised assets.networkId:<number>Network identifier (Ethereum = 1, Goerli = 5, Polygon = 137, Mumbai = 80001)init:<string>Transactions low limit to generate a public evidence.end:<string>Transactions upper limit to generate a public evidence.
Sample structure (Click to expand)
{
"init": "0",
"end": "1575975331"
}
Output
evidence:<json>
Sample structure (Click to expand)
{
"output": {
"networkId": 1,
"hash": "Ni7JYQG6GSmlEjWoRj2xrfF6ZVFhqBDPzyjk+o/HB2c=",
"timestamp": 1647522920,
"init": 0,
"end": 1592568489,
"smartContract": "0x1B646bc6C3465Fa8171F7171097A7d8e37b43D6B",
"transaction": "0x3d3d63714b62db4f28ef6d46911e864520db0645985dce250a80dc8bf6d35f6f",
"includedTransactions": [
{}
]
}
}
POST - /asset/{assetId}/getEvidence?isAuthorised=boolean¶
Get a specific asset evidence from the creation timestamp
Input
assetId:<string>Asset identifier.isAuthorised:<boolean>Flag to get own or authorised assets.timestamp:<string>Timestamp when the public evidence was generated.
Sample structure (Click to expand)
{
"timestamp": "1575975331"
}
Output
evidence:<json>
Sample structure (Click to expand)
{
"output": {
"networkId": 1,
"hash": "Ni7JYQG6GSmlEjWoRj2xrfF6ZVFhqBDPzyjk+o/HB2c=",
"timestamp": 1647522920,
"init": 0,
"end": 1592568489,
"smartContract": "0x1B646bc6C3465Fa8171F7171097A7d8e37b43D6B",
"transaction": "0x3d3d63714b62db4f28ef6d46911e864520db0645985dce250a80dc8bf6d35f6f",
"includedTransactions": [
{}
]
}
}
GET - /asset/{assetId}/getEvidences?isAuthorised=boolean¶
Get all asset evidences from public networks.
Input
assetId:<string>Asset identifier.isAuthorised:<boolean>Flag to get own or authorised assets.
Output
evidences:<json>
Sample structure (Click to expand)
{
"output": {
[
"networkId": 1,
"hash": "Ni7JYQG6GSmlEjWoRj2xrfF6ZVFhqBDPzyjk+o/HB2c=",
"timestamp": 1647522920,
"init": 0,
"end": 1592568489,
"smartContract": "0x1B646bc6C3465Fa8171F7171097A7d8e37b43D6B",
"transaction": "0x3d3d63714b62db4f28ef6d46911e864520db0645985dce250a80dc8bf6d35f6f",
"includedTransactions": [
{}
]
],
[
"networkId": 2,
"hash": "Ni7JYQG6GSmlEjWoRj2xrfF6ZVFhqBDPzyjk+o/HB2c=",
"timestamp": 1647522922,
"init": 0,
"end": 1592568489,
"smartContract": "0x1B646bc6C3465Fa8171F7171097A7d8e37b43D6B",
"transaction": "0x3d3d63714b62db4f28ef6d46911e864520db0645985dce250a80dc8bf6d35f6f",
"includedTransactions": [
{}
]
]
}
}
How we run the application¶
As you could see in the Architecture module, all the applications are running on cloud. Through Kubernetes orchestration system the application deployment, scaling and management is an easy and automated task.
Testing the Application¶
In postman folder there are the collection and environment to interact and test with the API methods. It is only needed to import them into postman application and know to use the coren-trackapi module.
Also you can download the files in the links below:
Errors management¶
Track API errors are managed through the following JSON:
{
"error": {
"code": "HTTP status code",
"function": "function in which the error was generated",
"message": "error description"
}
}