Description
This endpoint allows you to add a label to a file.
Authentication
Use the JSON Web Token (JWT) and the name of the organization to authenticate. For more details, see https://developers.tetrascience.com/reference/authentication.
Responses
Responses are in JSON format.
200 OK
Request was completed successfully. Results of the request appear in the table below.
| Parameter | Description | Type |
|---|---|---|
| name | Name of the label (Key) | string |
| value | Value of the label. | string |
401 Unauthorized
There is a problem with authorization. For details, see https://developers.tetrascience.com/reference/authentication.
404 Not Found
There was no API method associated with the endpoint you indicated.
500 Internal Server Error
There was a problem with the website’s server or a network issue.
Notes
Updating attributes such as metadata and tags without losing existing labels requires mulitple API calls. Keep in mind that when updating metadata or tags via the API, a new version of the file is created by TDP. The new version of the file will have a different File ID (fileID), so it will no longer be connected to labels that might have been previously associated with the file.
You can do update attributes using cURL, Postman or another similar client, or by placing the REST calls in Python.
Use cURL, Postman, or another Client to Update Attributes without Losing Existing Labels
- Make an API call to capture the existing labels on the file before performing a metadata and/or tags update.
GET 'https://api.tetrascience-dev.com/v1/fileinfo/file/my_fileId'
This returns a JSON response that contains the label and other information, such as when the label was created.
"labels": [
{
"name": "my_name_value",
"value": "my_label_value",
"id": 3871635,
"createdAt": "2021-10-06T14:36:19.721Z"
}
]
- Make an API call to update the metadata and tags and capture the new fileId as part of the response.
POST 'https://api.tetrascience-dev.com/v1/datalake/metadata-tags'
This returns a response like the following.
{
"originalFile": {
"fileId": "my_fileId_to_update"
},
"metadata": {
"my_metadata_name": "my_metadata_value"
},
"tags":["tag1", "tag2"]
}
Capture the new fileId that is part of the response
{
"fileId": "my_new_fileId",
"fileKey": "my/new/file/key",
"bucket": "ts-platform-dev-datalake",
"version": "LewF_zvOQJ6oEE.R1V_RTM5tNVsamzWY",
"type": "s3file"
}
- Inject the old (and new) labels as indicated in the call below.
POST 'https://api.tetrascience-dev.com/v1/fileinfo/files/my_new_fileId/labels'
[
{
"name":"my_(old)_label_name,
"value":"my_(old)_label_value"
}
]
Use Python to Update Attributes without Losing Existing Labels
The following shows sample Python code for updating attributes without losing existing labels.
import requests
import json
import numpy as np
#const variables for demo purposes
userEmail = "my_user_email"
password = "my_user_password"
orgSlug = "my_org_slug"
tetraURI = "https://api.tetrascience-dev.com"
testOriginalFile = "my_file_to_update"
testTags = ["postman1", "laptop2"] #tag values to add
testMetadata = {"new-via-api":"api-metadata-3"} #metadata values to add
testLabels = [{"name":"test-label-1", "value":"test-value-3"},{"name":"test-label-2", "value":"test-label-4"}] #label values to add
oldLabels = []
myLabels = []
#getting API token
tokenData = {"email":userEmail, "password":password}
tokenRequest = requests.post(tetraURI+'/login', data = tokenData)
tokenResponse = json.loads(tokenRequest.text)
print("token: " + tokenResponse["token"])
myApiToken = tokenResponse["token"]
#getting the existing labels
fileInfoHeader = {"ts-auth-token":myApiToken, "x-org-slug":orgSlug}
fileInfoRequest = requests.get(tetraURI+'/v1/fileinfo/file/'+testOriginalFile, headers = fileInfoHeader)
fileInfoResponse = json.loads(fileInfoRequest.text)
for labels in fileInfoResponse["labels"]:
tempLabelObject = {"name":labels["name"],"value":labels["value"]}
oldLabels.append(tempLabelObject)
myLabels = np.concatenate((oldLabels,testLabels)) #merging old & new labels into one object
print("labels on file: " + myLabels)
#updating the metadata & tags
updateMetadataHeader = {"ts-auth-token":myApiToken, "x-org-slug":orgSlug}
updateMetadataData = {
'originalFile':{'fileId':testOriginalFile},
'metadata':testMetadata,
'tags':testTags
}
updateMetadataRequest = requests.post(tetraURI+'/v1/datalake/metadata-tags', headers = updateMetadataHeader, json = updateMetadataData)
updateMetadataResponse = json.loads(updateMetadataRequest.text)
print("new fileId: " + updateMetadataResponse["fileId"])
newOriginalFile = updateMetadataResponse["fileId"] #saving the new fileId
#updating labels
updateLabelHeader = {"ts-auth-token":myApiToken, "x-org-slug":orgSlug}
updateLabelData = myLabels.tolist()
updateLabelRequest = requests.post(tetraURI+'/v1/fileinfo/files/'+newOriginalFile+'/labels', headers = updateLabelHeader, json = updateLabelData)
updateLabelResponse = json.loads(updateLabelRequest.text)
print(updateLabelResponse)