Hierarchy API

You can make hierarchical data available through hierarchy endpoints, which make available API features that are specific to hierarchical datasets. Each hierarchy endpoint corresponds to a single hierarchy scheme, and provides access to descriptions of the scheme and its members.

Scheme

You can access the hierarchy scheme description by sending a request to the root path of the hierarchy endpoint. For example, for a hierarchy endpoint for the scheme http://example.org/region, located at /api/region, a request sent to /api/region will return a description of that scheme.

You can also supply the following hierarchy-specific request parameters to your scheme request to obtain descriptions of the members of the scheme.

When requesting a list of hierarchy members, you can use all of the parameters normally accepted by list endpoints, including sorting, filtering and text search.

Note that the roots of the hierarchy are only members which are specifically defined as such, not simply those that have no parent.

Members

You can access the description of an individual hierarchy member by sending a request to a sub-path of the endpoint’s root path. The mapping of paths to members depends on the choice of locator configured on the endpoint spec.

If the members of the hierarchy all have URIs which extend the scheme URI, the endpoint should use the URI-based locator. In that case, in the example above, a request sent to /api/region/uk/england would return the member whose URI is http://example.org/region/uk/england.

Alternatively, if the hierarchy members do not have such URIs, the endpoint should use the hierarchy-based locator. In that case, a request sent to /api/region/uk/england would return the member whose identifier is “england”, and whose parent is a root member with the identifier “uk”.

You can also supply the following hierarchy-specific request parameters to your scheme request to obtain descriptions of related members of the scheme.

When requesting a list of hierarchy members, you can use all of the parameters normally accepted by list endpoints, including sorting, filtering and text search.

Hierarchical Sorting

When requesting a list of hierarchy members, you can order the results breadth-first or depth-first by supplying the _hsort (hierarchy sort) request parameter. The value of the parameter must be either breadth or depth respectively.

Note that you cannot supply both the usual _sort parameter and the _hsort parameter.

Recursive Properties

It is not necessary to define a hierarchy endpoint to be able to use the features of recursive properties. However, hierarchical data structures usually contain a recursive parent / child relation, and as such, if you include the class of hierarchy members in the view for some list endpoint, you will be able to define or request projections and paths which traverse those relations recursively (or inversely).