Properties and references

A number of API resources support storing arbitrary metadata. This is frequently useful for associating DNScaster resources with resources in your app.

Field: properties

Properties holds up to 20 key/value pairs:

{ "properties": {
    "myapp_id": "12345",
    "camelKey": "a,set,of,values",
    "from-user": "true",
    "most.kubernetes.style/annotations-will.work": "too"
  }
}

Keys and values must be simple strings. Keys may be 1-80 chars, must start with a letter, and must match [A-Za-z0-9_./-]+. Values may be 1-160 chars.

Arrays are not directly supported. Use something like a comma-separated, sorted list instead.

Field: external_ref

External ref holds a single string value from 4-50 chars. Values do not need to be unique.

{ "external_ref": "app_12345" }

Deprecated: external_ref has been succeeded by properties.

Setting properties

Resources with the properties field may generally set it during both Create and Update operations.

Sending properties will fully replace all existing values. To preserve any existing values, include them with the new payload. To remove values, simply exclude them from the new payload.

PUT /v1/hosts/hst_sample123456

{ "host": {
    "properties": { ... }
  }
}

Filtering by properties

Resources with properties may use it to filter results during List operations.

GET /v1/zones?properties[key1]=value1
GET /v1/zones?properties[key1]=value1&properties[key2]=value2

When 2 or more properties are provided, they are AND’d together. Only exact matches are returned.

Hint: Since empty property values are not persisted, querying for empty values will always return 0 results.