/api/tree/branch

A branch represents a level in the tree heirarchy and contains information about child branches and/or leaves. Branches are immutable from an API perspective and can only be created or modified by processing a TSMeta through tree rules via a CLI command or when a new timeseries is encountered or a TSMeta object modified. Therefore the branch endpoint only supports the GET verb.

A branch is identified by a branchId, a hexadecimal encoded string that represents the ID of the tree it belongs to as well as the IDs of each parent the branch stems from. All branches stem from the ROOT branch of a tree and this is usually the starting place when browsing. To fetch the ROOT just call this endpoingt with a valid treeId. The root branch ID is also a 4 character encoding of the tree ID.

Verbs

  • GET

Requests

The following fields can be used to request a branch. Only one or the other may be used.

Name

Data Type

Required

Description

Default

QS

RW

Example

treeId

Integer

Optional

Used to fetch the root branch of the tree. If used in combination with a branchId, the tree ID will be ignored.

treeid

RO

1

branch

String

Required

A hexadecimal representation of the branch ID, required for all but the root branch request

branch

RO

000183A21C8F

Response

A successful response to a request will return the branch object using the requested serializer. If the requested tree or branch did not exist in the system, a 404 will be returned with an error message.

Fields returned with the response include:

Name

Data Type

Description

Example

treeId

Integer

The ID of the tree the branch belongs to

1

displayName

String

Name of the branch as determined by the rule set

sys

branchId

String

Hexadecimal encoded ID of the branch

00010001BECD

depth

Integer

Depth of the branch within the tree, starting at 0 for the root branch

1

path

Map

List of parent branch names and their depth.

See Below

branches

Array

An array of child branch objects. May be null.

See Below

leaves

Array

An array of child leaf objects. May be null.

See Leaves Below

Leaves

If a branch contains child leaves, i.e. timeseries stored in OpenTSDB, their metric, tags, TSUID and display name will be contained in the results. Leaf fields are as follows:

Name

Data Type

Description

Example

metric

String

The name of the metric for the timeseries

sys.cpu.0

tags

Map

A list of tag names and values representing the timeseries

See Below

tsuid

String

Hexadecimal encoded timeseries ID

000001000001000001

displayName

String

A name as parsed by the rule set

user

GET

Example Root GET Query

  1. http://localhost:4242/api/tree/branch?treeid=1

Example Response

  1. {
  2. "leaves": null,
  3. "branches": [
  4. {
  5. "leaves": null,
  6. "branches": null,
  7. "path": {
  8. "0": "ROOT",
  9. "1": "sys"
  10. },
  11. "treeId": 1,
  12. "displayName": "sys",
  13. "branchId": "00010001BECD",
  14. "depth": 1
  15. }
  16. ],
  17. "path": {
  18. "0": "ROOT"
  19. },
  20. "treeId": 1,
  21. "displayName": "ROOT",
  22. "branchId": "0001",
  23. "depth": 0
  24. }

Example Branch GET Query

  1. http://localhost:4242/api/tree/branch?branchid=00010001BECD000181A8

Example Response

  1. {
  2. "leaves": [
  3. {
  4. "metric": "sys.cpu.0.user",
  5. "tags": {
  6. "host": "web01"
  7. },
  8. "tsuid": "000001000001000001",
  9. "displayName": "user"
  10. }
  11. ],
  12. "branches": [
  13. {
  14. "leaves": null,
  15. "branches": null,
  16. "path": {
  17. "0": "ROOT",
  18. "1": "sys",
  19. "2": "cpu",
  20. "3": "mboard"
  21. },
  22. "treeId": 1,
  23. "displayName": "mboard",
  24. "branchId": "00010001BECD000181A8BF992A99",
  25. "depth": 3
  26. }
  27. ],
  28. "path": {
  29. "0": "ROOT",
  30. "1": "sys",
  31. "2": "cpu"
  32. },
  33. "treeId": 1,
  34. "displayName": "cpu",
  35. "branchId": "00010001BECD000181A8",
  36. "depth": 2
  37. }