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.

ParameterDescriptionType
nameName of the label (Key)string
valueValue 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

  1. 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"
        }
    ]
  1. 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"
}
  1. 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)
Language
Authentication
Click Try It! to start a request and see the response here!