DTS API
This is an introduction page for the DTS (Data Traceability Service) API.
About DTS API
The DTS API of ChainZ API Service allows you to trace the access status history of data based on ERC721 tokens.
It provides functions for saving access status (e.g. CREATED, SENT, RECEIVED, DELETED, ANALYZED, RESULT, CHANGE_STATE) and searching the access status history and the metadata of the data.
Using the DTS API
Common settings
ChainZ DTS API URL: https://dts-api.chainz.biz
Common HTTP Request
In order to access the API, the access token and API key must always be included in the HTTP Header.
curl -X POST \
"https://{DTS API Url}" \
-H "accept: application/json" \
-H "Authorization: Bearer {access token}" \
-H "x-api-key: {API key}" \
-H 'Content-Type: application/json' \
-d '{Json Body}'ChainZ Provider Information Registration
For using the DTS API, you need to register the information about the ChainZ provider first. You can use "API to register ChainZ provider" and "API to register ChainZ provider's permission to blockchain" in order to register the information.
1) ChainZ Provider Registration
URL: https://shared-dts-api.chainz.biz/api/v1/admin/chainz-providers
Request
{
"providerCode": <ChainZ provider code>,
"companyName": <Name of the company which is managed by the provider>,
"email": <Company administrator's email address>,
"userName": <Company administrator's name>
}Response
{
"success": true,
"result": {
"userId": <Company administrator's ID>,
"userName": <Company administrator's name>,
"email": <Company administrator's email>,
"companyInfo": {
"id": <Company ID>,
"name": <Company name>
},
"userType": <Type of the company administrator>,
"userRole": <Role of the company administrator>,
"createdAt": <Creation Date time>,
"departmentInfo": {
"id": <Department ID>,
"name": <Department name>
},
"useYn": <Usage status>
},
}2) Registering Permission to Blockchain
URL: https://shared-dts-api.chainz.biz/api/v1/admin/chainz-providers/chain
Request
{
"providerCode": <ChainZ provider code>,
"chainIds": <ChainZ blockchain ID List>
}Response
{
"success": true,
"result": true
}1. Data Registration
Register metadata of the data. The data access information for CREATED is saved.
URL : https://shared-dts-api.chainz.biz/api/v1/data
Request
{
"fileName": <Data(File) name>,
"genTime": <Data generation time>,
"providerId": <ID of a user who actually provides the data>,
"chainId": <Chain ID>,
"hashType": <Type of hashing algorithm>,
"hash": <Hash value of the data>,
"expTime": <Data expired time>,
"actorId": <ID of a user who actually accesses the data>,
"receiverIds": <ID list of users who receive the data>,
"parentDataIds": <Parent data ID list of the data>,
"fileExtension": <Type of file extenstion>,
"fileSize": <File size>,
"hashSize": <Size of the hashed file>,
"productInfo": {
"productId": <Product ID>,
"productName": <Product name>,
"description": <Product description>,
"tags": <Product tags>,
"dataType": <Data type of the product>,
"productType": <Product type>,
"dataFormat": <Schema of the product>,
"dataSample": <Sample of the product>,
"license": <Product licence>,
"company": <Company name>,
}
}Response
{
"success": true,
"result": {
"dataInfo": {
"dataId": <Data ID>,
"fileName": <Data(File) name>,
"hashType": <Type of hashing algorithm>>,
"hash": <Hash value of the data>,
"genTime": <Data generation time>,
"expTime": <Data expired time>,
"generation": <Generation number of the data>,
"providerId": <ID of a user who actually provides the data>,
"providerCode": <ChainZ provider code>,
"chainId": <Chain ID>,
"fileExtension": <Type of file extenstion>,
"fileSize": <File size>,
"hashSize": <Size of the hashed file>,
"actorId": <ID of a user who actually accesses the data>,
"receiverIds": <ID list of users who receive the data>,
"parentDataIds": <Parent data ID list of the data>,
"ownerInfo": {
"userId": <Data owner(provider) ID>,
"userName": <Data owner name>,
"email": <Data owner email>,
"userRole": <Role of the Data owner>,
},
"sharedDepartmentList": [
{
"id": <ID of a department which can access to the data>,
"name": <Name of a department which can access to the data>,
}
],
"dataProduct": <Data product information>,
"traceInfo": {
"traceId": <Trace(history) ID>,
"dataId": <Data ID>,
"actionInfo": {
"actionId": <Data access action ID>,
"actionCode": <Data access action code>,
"actionName": <Data access action name>,
"actionImgUrl": <Image URL of the data access action icon>,
"actionBgColor": <Backgraoud color of the data access action icon>,
"sequence": <Data access action sequence>,
},
"accessTime": <Data access time>,
"transactionHash": <Transaction hash that is given when the trace information is verified and added to the blockchain>,
"blockNumber": <Number of the block which is mined including the transaction>,
"status": <Transaction status>,
"accessorId": <ID of a client who actually performs this request>,
"actorId": <ID of a user who actually accesses the data>,
}
}
}2. Creating Data Access History
Create the data access history(trace). The types of access status are SENT, RECEIVED, DELETED, ANALYZED, RESULT, CHANGE_STATE, etc.
URL : https://shared-dts-api.chainz.biz/api/v1/data/{dataId}/access
Request
{
"dataAccessType": <Type of data access status>,
"chainId": <Chain ID>,
"actorId": <ID of a user who actually accesses the data>,
"messageHash": <Hash value of the message>,
"message": <Message for data access status>,
"toId": <ID of a user who receive the data - Required for "SENT">,
"fromId": <ID of a user who send the data - Required for "RECEIVED">,
}Response
{
"success": true,
"result": {
"traceId": <Trace(history) ID>,
"dataId": <Data ID>,
"actionInfo": <Data access action information>,
"accessTime": <Data access time>,
"messageHash": <Hash value of the message>,
"message": <Message for data access status>,
"toId": <ID of a user who receive the data - Required for "SENT">,
"fromId": <ID of a user who send the data - Required for "RECEIVED">,
"transactionHash": <Transaction hash that is given when the trace information is verified and added to the blockchain>,
"blockNumber": <Number of the block which is mined including the transaction>,
"status": <Transaction status>,
"accessorId": <ID of a client who actually performs this request>,
"actorId": <ID of a user who actually accesses the data>,
"resultInfo": {
"resultDataId": <ID of the output which is generated based on the data>,
"parents": <Parent data of the output>
}
}
}3. Searching Data List
Search the list of data.
URL : https://shared-dts-api.chainz.biz/api/v1/data
Request
Query parameters
- dataID: Data ID - providerId: ID of a user who actually provides the data - providerName: Name of a user who actually provides the data - fileName: Data(file) name - hash: Hash value of the data - fromGenTime: Start time to query the data generation time - toGenTime: End time to query the data generation time - fromRecentAccessTime: Start time to query the last access time to the data - toRecentAccessTime: End time to query the last access time to the data - currentActionId: ID of the last data access action - offset: Offset value for paging - limit: Limit value for paging
Response
{
"success": true,
"result": {
"totalElements": <The total number of data>,
"totalPages": <The number of pages>,
"content": [
{
"dataId": <Data ID>,
"providerId": <ID of a user who actually provides the data>,
"providerName": <Name of a user who actually provides the data>,
"fileName": <Data(file) name>,
"genTime": <Data generation time>,
"providerCode": <ChainZ provider code>,
"chainId": <Chain ID>,
"traceCount": <The number of access status histories of the data>,
"lastTraceTime": <The last trace time>,
"lastActionInfo": <The last data access action information>,
"ownerInfo": {
"userId": <Data owner ID>,
"userName": <Data owner name>,
"email": <Data owner email>,
"userRole": <Role of the Data owner>,
}
}
]
}
}4. Searching Data Information
Search the data information.
URL : https://shared-dts-api.chainz.biz/api/v1/data/{dataId}
Request
Request parameter
- dataID: Data ID
Response
{
"success": true,
"result": {
"dataId": <Data ID>,
"fileName": <Data(File) name>,
"hashType": <Type of hashing algorithm>>,
"hash": <Hash value of the data>,
"genTime": <Data generation time>,
"expTime": <Data expired time>,
"generation": <Generation number of the data>,
"providerId": <ID of a user who actually provides the data>,
"providerCode": <ChainZ provider code>,
"chainId": <Chain ID>,
"fileExtension": <Type of file extenstion>,
"fileSize": <File size>,
"hashSize": <Size of the hashed file>,
"actorId": <ID of a user who actually accesses the data>,
"receiverIds": <ID list of users who receive the data>,
"parentDataIds": <Parent data ID list of the data>,
"ownerInfo": <Data owner information>,
"sharedDepartmentList": <List of the departments which can access to the data>,
"dataProduct": <Data product information>
}
}5. Searching Data Access History (Trace) List
Search the list of data access history(trace).
URL : https://shared-dts-api.chainz.biz/api/v1/traces
Request
Query parameters
- providerId: ID of a user who actually provides the data - txHash: Transaction hash that is given when the trace information is verified and added to the blockchain - fileName: Data(file) name - dataID: Data ID - accessorName: Name of a client who actually performs this request - actorName: Name of a user who actually accesses the data - accessActionId: ID of the data access action - fromAccessTime: Start time to query the access time to the data - toAccessTime: End time to query the access time to the data - offset: Offset value for paging - limit: Limit value for paging
Response
{
"success": true,
"result": {
"totalElements": <The total number of data>,
"totalPages": <The number of pages>,
"content": [
{
"traceId": <Trace(history) ID>,
"dataId": <Data ID>,
"actionInfo": <Data access action information>,
"accessTime": <Data access time>,
"messageHash": <Hash value of the message>,
"message": <Message for data access status>,
"toId": <ID of a user who receive the data - Required for "SENT">,
"fromId": <ID of a user who send the data - Required for "RECEIVED">,
"transactionHash": <Transaction hash that is given when the trace information is verified and added to the blockchain>,
"blockNumber": <Number of the block which is mined including the transaction>,
"status": <Transaction status>,
"dataInfo": {
"dataId": <Data ID>,
"fileName": <Data(File) name>
},
"actor": {
"userId": "ID of a user who actually accesses the data",
"userName": "Name of a user who actually accesses the data"
},
"accessor": {
"userId": "ID of a client who actually performs this request",
"userName": "Name of a client who actually performs this request"
},
"resultInfo": {
"resultDataId": <ID of the output which is generated based on the data>,
"parents": <Parent data of the output>
}
}
]
}
}6. Searching Data Access History (Trace) Information
Search the data access history(trace) information.
URL : https://shared-dts-api.chainz.biz/api/v1/traces/{traceId}
Request
Request parameter
- traceID: Trace ID
Response
{
"success": true,
"result": {
"traceId": <Trace(history) ID>,
"dataId": <Data ID>,
"actionInfo": <Data access action information>,
"accessTime": <Data access time>,
"messageHash": <Hash value of the message>,
"message": <Message for data access status>,
"toId": <ID of a user who receive the data - Required for "SENT">,
"fromId": <ID of a user who send the data - Required for "RECEIVED">,
"transactionHash": <Transaction hash that is given when the trace information is verified and added to the blockchain>,
"blockNumber": <Number of the block which is mined including the transaction>,
"status": <Transaction status>,
"dataInfo": {
"dataId": <Data ID>,
"fileName": <Data(File) name>
},
"actor": {
"userId": "ID of a user who actually accesses the data",
"userName": "Name of a user who actually accesses the data"
},
"accessor": {
"userId": "ID of a client who actually performs this request",
"userName": "Name of a client who actually performs this request"
},
"resultInfo": {
"resultDataId": <ID of the output which is generated based on the data>,
"parents": <Parent data of the output>
}
}
}List of DTS APIs
Last updated