The Metadata Rest API is a way to write data to the datastore in name/value pairs. Data is written separate from the time series data. Metadata is partitioned by a service name. A service partition can have multiple service keys. Each service key holds name/value pairs. A value is a string.
Example
Assume you have a service that maintains metadata about each metric. Let’s call it the Metric Service. Your service associates each metric with a description, owner, and the unit type. The service name is “Metric Service”, the metric is the service key and the name/value pairs are the owner, unit, and description and their values.
Metric Service
| Metric | Owner | Unit | Description |
|---|---|---|---|
| disk.available | OPs team | MB | Available disk space |
| foo.throughput | Foo team | Bytes | Number of bytes |
Add a value to service metadata.
POST
http://[host]:[port]/api/v1/metadata/{service}/{serviceKey}/{key}
<The Value>
Writes the value for the given service, service key, and key.
service The name of the service.
serviceKey The name of the service key.
key The name of the key.
value The value to store. The value must be a string.
Success
Returns 204 when successful.
Failure
The response will be 500 Internal Server Error if an error occurs writing the value.
{ "errors": [ "Failed to add value" ] }
Returns the value for the given service.
GET
http://[host]:[port]/api/v1/metadata/{service}/{serviceKey}/{key}
None
Returns the value for the given service, service key, and key if it exists or an empty response if it does not exist.
service The name of the service.
serviceKey The name of the service key.
key The name of the key.
Success
The response contains the value or an empty string if not found. Returns 200 when successful.
Failure
The response will be 500 Internal Server Error if an error occurs writing the value.
{ "errors": [ "Failed to retrieve value" ] }
Returns all service keys for the given service
GET
http://[host]:[port]/api/v1/metadata/{service}
None
Returns all keys for the given service or an empty list if no service keys exist for the given service.
service The name of the service.
Success
{ "results":["service_key_1", "service_key_2"] }The response contains a list of service keys for the given service or an empty string if not found. Returns 200 when successful.
Failure
The response will be 500 Internal Server Error if an error occurs writing the value.
{ "errors": [ "Failed to get keys" ] }
Returns all keys for the given service and service key.
GET
http://[host]:[port]/api/v1/metadata/{service}/{serviceKey}
None
Returns all keys for the given service key or an empty list if no keys exist.
service The name of the service.
serviceKey The name of the service key.
Success
{ "results":["key_1", "key_2"] }The response contains a list of keys for the given service key or an empty string if not found. Returns 200 when successful.
Failure
The response will be 500 Internal Server Error if an error occurs writing the value.
{ "errors": [ "Failed to get keys" ] }
Deletes the specified key.
DELETE
http://[host]:[port]/api/v1/metadata/{service}/{serviceKey}/{key}
None
Delete the given key if it exists.
service The name of the service.
serviceKey The name of the service key.
key The name of the key.
Success
Returns 204 when successful.
Failure
The response will be 500 Internal Server Error if an error occurs writing the value.
{ "errors": [ "Failed to delete key" ] }