Unicat API Reference

Up - API Reference - Home

/api/p/<project gid>/records/tree

Requires JWT.

Get the tree, paginated.

This endpoint is meant to power a UI with a scrolling tree-navigation for the records. The UI keeps track of which records are currently expanded or not (expanded_records), the scroll position (page.top) and panel size (page.size, how many records fit in the panel) for the tree.

The returned result is an ordered, flat list of records; but each record knows its indentation level (treelevel) and if it's expandable (childcount).

You can specify which languages you want in the results.

Note: unlike most records/… endpoints, this endpoint only returns metadata in the data records, so without the fields.

Request

POST /api/p/<project gid>/records/tree
Authorization: Bearer <JWT>

{
    "expanded_records": [
        "d96073b1-69da-493e-8433-3820c8cca3a8",
        "e8c7a57f-c83f-408b-b0a1-7625894dabd6"
    ],
    "language": "nl",
    "ordering": "87b53a4e-359d-45c7-81cb-5e1c3ef444ec",
    "page.top": 0,
    "page.size": 10
}

expanded_records is the list of records for the complete tree that are currently expanded.
ordering return the tree in this order.

Note: channel is never used for this endpoint.

optional

language return data for this (project) language.
languages return data for these (project) languages.
page.top (default 0) only return records starting from the top-index (0-based).
page.size (default 100) only return this many records.

Note: if the tree size is 100, the page size is 10, and the page top is 95, you'll actually get the last 10 records (starting from 90, not 95) - this is to prevent the UI from scrolling to the end and only showing the very last record, instead of keeping the panel nicely filled.

If you request language and/or languages, you get the records' title for the combined set. If you request neither, you'll get all available languages.

Success response

Authorization: <JWT>

{
    "success": true,
    "result": {
        "tree": [
            "d96073b1-69da-493e-8433-3820c8cca3a8",
            "e8c7a57f-c83f-408b-b0a1-7625894dabd6",
            …
        ],
        "tree.size": 10
    },
    "data": {
        "records": {
            "d96073b1-69da-493e-8433-3820c8cca3a8": {
                "gid": "d96073b1-69da-493e-8433-3820c8cca3a8",
                "parent": null,
                "treelevel": 0,
                "childcount": 2,
                "path": [
                    "d96073b1-69da-493e-8433-3820c8cca3a8"
                ],
                "title": {"nl": "Project"},
                …
            },
            "e8c7a57f-c83f-408b-b0a1-7625894dabd6": {
                "gid": "e8c7a57f-c83f-408b-b0a1-7625894dabd6",
                "parent": "d96073b1-69da-493e-8433-3820c8cca3a8",
                "treelevel": 1,
                "childcount": 6,
                "path": [
                    "e8c7a57f-c83f-408b-b0a1-7625894dabd6",
                    "d96073b1-69da-493e-8433-3820c8cca3a8"
                ],
                "title": {"nl": "Catalogus"},
                …
            },
            …
        }
    }
}

result

tree the requested paginated records, in ordering order.
tree.size the size of the non-paginated tree for expanded_ids.

data

records Record info with hierarchy (gid, parent, treelevel, childcount), definition, title. Unordered.

Note: the data records only contain metadata, not the defined fields.

For each record, you can use treelevel to determine the indentation, and childcount to see if this record is expandable.

Error responses

400 Bad request - missing parameters or wrong type or value
401 Unauthorized - missing or expired JWT
403 Forbidden - not a member of this project