Tags 🔗

Catalog 🔗

/datasets/{id}/tags/

GET 🔗

A GET request on this resource returns a Shoji Catalog exposing the “variable tags” present in the Dataset.

{
    "element": "shoji:catalog",
    "self": "https://app.crunch.io/api/datasets/223fd4/tags/",
    "index": {
        "https://app.crunch.io/api/datasets/223fd4/tags/tag1/": {
          "name": "tag1"
        },
        "https://app.crunch.io/api/datasets/223fd4/tags/tag2/": {
          "name": "tag2"
        }
    }
}

The catalog tuples contain the following keys:

Name Type Description
name string Human-friendly string identifier

The list of variables attached to a particular “variable tag” are not exposed in the catalog. To obtain them, the corresponding “variable tag” Entity must be accessed.

POST 🔗

You can declare variable tags on dataset creation using the tags member, or individually as follows.

A POST to this resource adds a new “variable tag”. The request payload must contain the name of the new tag.

{
  "body": {
      "name": "<name_of_new_tag>"
  }
}

The only allowed characters for tag names are: (unicode) letters, numbers, underscores and spaces; any other character is forbidden. Furthermore, tag names cannot be blank or consist only of space characters. The maximum allowed length for tag names is 20 characters.

Optionally, the request payload may contain the initial list of variable urls that are to be attached to the new tag:

{
  "body": {
      "name": "<name_of_new_tag>",
      "variables": [
          "<var_url_1>",
          "<var_url_2>",
          "..."
      ]
  }
}

A successful request will return a 201 status. The newly created “variable tag” entity’s URL is returned in the Location header.

Entity 🔗

/datasets/{id}/tags/{tag_name}/

GET 🔗

A GET on this resource returns a Shoji Entity describing the “variable tag”, including the list of variables it contains.

{
    "element": "shoji:entity",
    "self": "https://app.crunch.io/api/datasets/223fd4/tags/tag1/",
    "body": {
        "name": "tag1",
        "variables": [
            "https://app.crunch.io/api/datasets/223fd4/variables/00000/",
            "https://app.crunch.io/api/datasets/223fd4/variables/00001/",
            "https://app.crunch.io/api/datasets/223fd4/variables/99999/"
        ]
    }
}
Name Type Description
name string Human-friendly string identifier
variables list List of variables attached to the tag (expressed as URLs)

PATCH 🔗

To edit a “variable tag”, PATCH it with a shoji:entity object. The server will return a 204 response on success or 400 if the request is invalid.

Adding or deleting variables is achieved by modifying the variables attribute to contain the desired variable URLs. Clearing the variables in the tag can be done by setting the variables attribute to an empty list ([]).

{
    "element": "shoji:entity",
    "body": {
        "name": "tag1",
        "variables": [
            "https://app.crunch.io/api/datasets/223fd4/variables/00000/",
            "https://app.crunch.io/api/datasets/223fd4/variables/00001/"
        ]
    }
}
HTTP/1.1 204 No Content

DELETE 🔗

To delete a “variable tag”, DELETE its entity URL. On success, the server returns a 204 response.