Render Variables API

Contents

• Render Variables API

  • Creating a variable

  • Updating a variable

  • Search variables

  • Get variable values

  • Delete a variable

  • Graphing with render variables

Render Variables provide versatility when constructing metric queries. Instead of hard-coding full metric names, use variables as placeholders to dynamically build your queries. This is similar, but not the same as the primary dashboard’s built-in template variables.

NOTE: we advise against using render variables in alert queries.

Creating a variable

Create a variable

POST /v1/variables/<var-name>/

Replace <var-name> with the name you want to give the variable. Place your variable values in a JSON file and include it in the POST request. A variable name is required, however the values can be empty.

201: Created { "url": "/v1/variables/<var-name>/" }

400: Bad Request JSON could be incorrectly formatted or the variable name already exists

Example variable values:

{
  "values": [
    "foobar",
    "foo",
    "bar",
    "baz"
  ]
}

Curl example:

curl -X POST "https://[email protected]/v1/variables/<var-name>/" -d @values.json

Make sure to include the forward slash character at the end of the request.

---

Updating a variable

Update a variable

PUT /v1/variables/<var-name>/

Overwrites the values for an existing variable

200: OK { "url": "/v1/variables/<var-name>/" }

400: Bad Request JSON could be incorrectly formatted

404: Not Found

Curl example:

curl -X PUT "https://<apikey>@api.hostedgraphite.com/v1/variables/<var-name>/" -d @values.json

---

Search variables

Search Variables

GET /v1/variables/?query=

A “contains” query that will return a JSON object with the name and path of variables that contain the search term. To list all variables, leave the query empty.

Path Parameters

Name	Type	Description
query	String

200: OK { "variables" : [ { "name" : "foo", "url" : "/v1/variables/foo/" }, { "name" : "bar", "url" : "/v1/variables/bar/" } ] }

Curl example:

curl -X GET "https://<apikey>@api.hostedgraphite.com/v1/variables/?query="

If you have no variables or there are no variables that match your query you will be returned with an empty object:

{
  "variables": []
}

---

Get variable values

Get variable values

GET /v1/variables/<var-name>/

Returns a JSON object with the values assigned to <var-name>

200: OK { "values": [ "foobar", "foo", "bar", "baz" ] }

404: Not Found

Curl example:

curl -X GET "https://<apikey>@api.hostedgraphite.com/v1/variables/<var-name>/"

---

Delete a variable

Delete a variable

DELETE /v1/variables/<var-name>/

200: OK

404: Not Found

Curl example:

curl -X DELETE "https://<apikey>@api.hostedgraphite.com/v1/variables/<var-name>/"

---

Graphing with render variables

This cannot be done with the simple query builder, you must toggle the edit mode to the free-text mode.

Refer to a render variable by including the variable name enclosed in angled brackets in your metric query: <variable-name>

Using dashboard templates within render variables

You can place template variables within render variables by surrounding them with curly brackets:

$foo.<{$foo}_metric>.bar