Implement GET /devices/hierarchy/:topic in Python Client Library

[davidraker]

Retrieve a partial topical hierarchy of all devices on all platforms.

Note: Device endpoints accept query parameters to refine their output, as described in the introduction to the Devices section.

Note: See the introduction to the Devices section for information on the use of topics.

As with the GET /devices/hierarchy endpoint, the response provides a dictionary organized hierarchically by segments within the device topic. Providing a partial topic produces a clade of the device tree with its root at the provided topic.

As elaborated on in the introduction to the Devices section, there is no special meaning to the segments of device topics, but the example response shown here assumes that devices are organized in a pattern common for a campus of buildings: /:campus/:building/:device/:point. Using a partial topic: /:campus/:building will produce a the same object which could be obtained by indexing the response of GET /devices/hierarchy first with <campus> and then n<device>, e.g.:

```
    responseObject['<campus>']['<building>']
```

The example shown in the response section below is produced by GET /devices/hierarcy/:campus/:building, where :building has the same value as the second building in the example shown for GET /devices/hierarchy.

Providing a full topic will usually produce a single leaf node, except where more than one connected platform has the same topic, in which case the result will be the list of leaf nodes corresponding to that topic on each containing platform.

⚠️ It is not necessary that topics all have the same number of segments, therefore some parts of the tree may be deeper than others. Users should not assume a uniform depth to all branches of the tree. It is also possible that a given level of the tree is not uniformly either a dict or a string. For example, in the third building shown in the example, zone level devices have an extra segment to indicate they are served by a particular air handling unit, however the air handling unit device itself has the normal number of segments.

Request:

• Authorization: BEARER <jwt_token>

Response:

• With valid BEARER token on success: 200 OK 201 Created 204 No Content
  • Content Type: application/json
  • Body:

        "<device>": "/platforms/:platform/devices/:topic/",
         "<device>": [
                "/platforms/:platform1/devices/:topic/",
                "/platforms/:platform2/devices/:topic/",
                ...
            ],
            ...
        }
    }
    

• With valid BEARER token on failure: 400 Bad Request
  • Content Type: application/json
  • Body:

    {
        "error": "<Error Message>"
    }
    

• With invalid BEARER token: 401 Unauthorized