Labels

A label is a pair of a key and value assigned to a certain resource. Thus, you can group related resources under the same tag.

The key may consist either of one name or two prefix/name parts:

prefix — an optional part;
name — a required part.

The value is a string of data associated with the key. The label pattern in the Servers.com Public API looks like this: "prefix/name": "value" or "name": "value".

Limitations

A resource can have several labels but each key must be unique.
The key can consist of Latin letters [A...z], digits [0...9], dashes (-), dots (.).
The prefix may contain only lowercase letters.
The value can consist of Latin letters [A...z], digits [0...9], dashes (-), dots (.), underscore (_).
The prefix, name, and value may start and end only with Latin letters or numbers.
The maximum length of the prefix is 253 characters, and a dot-separated part is limited to 63 characters.
The maximum length of name and value is 63 symbols.
The servers.com/ prefix can't be used.

Labels usage

Public API resources have the labels parameter that contains all the labels associated with the resource. Labels can be edited within the request body of POST or UPDATE requests. This is an example of how to fill in labels:

"labels": {
     "environment": "production",
     "service": "my-web-app",
     "example.com/project": "my-project",
     "example.com/owner": "my-team"
}

To delete a label, include all existing labels in the request body, excluding the label you want to remove.

Add label

This cURL PUT request adds the labels "environment": "production" and "service": "my-web-app" to a dedicated server with the ex4mp1e ID.

curl "https://api.servers.com/v1/hosts/dedicated_servers/ex4mp1e" -d '{
  "labels": {
    "environment": "production",
    "service": "my-web-app"
  }
}' -X PUT \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TOKEN"

Edit label

To update a label, for example, moving a server from production to the testing environment, perform the following request:

curl "https://api.servers.com/v1/hosts/dedicated_servers/ex4mp1e" -d '{
  "labels": {
    "environment": "testing",
    "service": "my-web-app"
  }
}' -X PUT \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TOKEN"

Remember to include all labels that shouldn't be removed, including those you aren't changing. Otherwise, they'll be removed.

Delete label

To delete a label, do the same PUT request without mentioning the label you want to remove. In the below example, we've decided to take out the service label.

curl "https://api.servers.com/v1/hosts/dedicated_servers/ex4mp1e" -d '{
  "labels": {
    "environment": "testing"
  }
}' -X PUT \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TOKEN"

Labels selector

A list of resources can be filtered by labels. That's why a GET request for listing has the label_selector query parameter. The table below shows syntax for writing labels selector rules:

Symbol	Description
,	Comma separates one condition from another (AND join).
==	The value of a key equals the value specified in a request. Also, the single = symbol does the same.
!=	The value of a key doesn't equal the value specified in a request.
key	If a key is specified without other symbols, it means the key must be present.
!key	A key must not be present.
key in (value1, value2)	The value of a key is value1 or value2.
key notin (value1, value2)	The value of a key is not value1 or value2.

A request URL to find all operating production servers for a DevOps team might look like this:

https://api.servers.com/v1/hosts?label_selector=environment==production,techdepartment/team==devops,state!=maintenance

Note that some HTTP clients may require an encoded URL.

Example of an encoded URL:

https%3A%2F%2Fapi.servers.com%2Fv1%2Fhosts%3Flabel_selector%3Denvironment%3D%3Dproduction%2Ctechdepartment%2Fteam%3D%3Ddevops%2Cstate%21%3Dmaintenance