/api/uid/uidmeta

/api/uid/uidmeta

This endpoint enables editing or deleting UID meta data information, that is meta data associated with metrics, tag names and tag values. Some fields are set by the TSD but others can be set by the user. When using the POST method, only the fields supplied with the request will be stored. Existing fields that are not included will be left alone. Using the PUT method will overwrite all user mutable fields with given values or defaults if a given field is not provided.

Note

Deleting a meta data entry will not delete the UID assignment nor will it delete any data points or associated timeseries information. Deletion only removes the specified meta data object, not the actual value. If you query for the same UID, you’ll see the default meta data with empty fields.

Verbs

GET - Query string only
POST - Updates only the fields provided
PUT - Overwrites all user configurable meta data fields
DELETE - Deletes the UID meta data

Requests

Fields that can be supplied with a request include:

Name	Data Type	Required	Description	Default	QS	RW	Example
uid	String	Required	A hexadecimal representation of the UID		uid	RO	00002A
type	String	Required	The type of UID, must be `metric`, `tagk` or `tagv`		type	RO	metric
description	String	Optional	A brief description of what the UID represents		description	RW	System processor time
displayName	String	Optional	A short name that can be displayed in GUIs instead of the default name		display_name	RW	System CPU Time
notes	String	Optional	Detailed notes about what the UID represents		notes	RW	Details
custom	Map	Optional	A key/value map to store custom fields and values	null		RW	See Below

Note

Custom fields cannot be passed via query string. You must use the POST or PUT verbs.

Warning

If your request uses PUT, any fields that you do not supply with the request will be overwritten with their default values. For example, the description field will be set to an emtpy string and the custom field will be reset to null.

Example GET Request

http://localhost:4242/api/uid/uidmeta?uid=00002A&type=metric

Example POST or PUT Request

Query String:

http://localhost:4242/api/uid/uidmeta?uid=00002A&type=metric&method=post&display_name=System%20CPU%20Time

JSON Content:

{
    "uid":"00002A",
    "type":"metric",
    "displayName":"System CPU Time",
    "custom": {
        "owner": "Jane Doe",
        "department": "Operations",
        "assetTag": "12345"
    }
}

Example DELETE Request

Query String:

http://localhost:4242/api/uid/uidmeta?uid=00002A&type=metric&method=delete

JSON Content:

{
    "uid":"00002A",
    "type":"metric"
}

Response

A successful response to a GET, POST or PUT request will return the full UID meta data object with any given changes. Successful DELETE calls will return with a 204 status code and no body content. When modifying data, if no changes were present, i.e. the call did not provide any data to store, the response will be a 304 without any body content. If the requested UID did not exist in the system, a 404 will be returned with an error message. If invalid data was supplied an error will be returned.

All Request fields will be present in the response in addition to a couple of others:

Name	Data Type	Description	Example
name	String	The name of the UID as given when the data point was stored or the UID assigned	sys.cpu.0
created	Integer	A Unix epoch timestamp in seconds when the UID was first created. If the meta data was not stored when the UID was assigned, this value may be 0.	1350425579

Example Response

{
    "uid": "00002A",
    "type": "TAGV",
    "name": "web01.mysite.com",
    "description": "Website hosting server",
    "notes": "This server needs a new boot disk",
    "created": 1350425579,
    "custom": {
        "owner": "Jane Doe",
        "department": "Operations",
        "assetTag": "12345"
    },
    "displayName": "Webserver 01"
}