API: Retrieve zettel order within an existing zettel

00001012054000 · Info · (manual) · #api #manual #zettelstore

Some zettel act as a “table of contents” for other zettel. The initial zettel of this manual is one example, the general API description is another. Every zettel with a certain internal structure can act as the “table of contents” for others.

What is a “table of contents”? Basically, it is just a list of references to other zettel.

To retrieve the “table of contents”, the software looks at first level list items. If an item contains a valid reference to a zettel, this reference will be interpreted as an item in the table of contents.

This applies only to first level list items (ordered or unordered list), but not to deeper levels. Only the first reference to a valid zettel is collected for the table of contents. Following references to zettel within such an list item are ignored.

To retrieve the zettel order of an existing zettel, use the endpoint /o/{ID}.

# curl http://127.0.0.1:23123/o/00001000000000
{"id":"00001000000000","url":"/z/00001000000000","meta":{...},"list":[{"id":"00001001000000","url":"/z/00001001000000","meta":{...}},{"id":"00001002000000","url":"/z/00001002000000","meta":{...}},{"id":"00001003000000","url":"/z/00001003000000","meta":{...}},{"id":"00001004000000","url":"/z/00001004000000","meta":{...}},...,{"id":"00001014000000","url":"/z/00001014000000","meta":{...}}]}

Formatted, this translates into:1

{
  "id": "00001000000000",
  "url": "/z/00001000000000",
  "order": [
    {
      "id": "00001001000000",
      "url": "/z/00001001000000",
      "meta": {...}
    },
    {
      "id": "00001002000000",
      "url": "/z/00001002000000",
      "meta": {...}
    },
    {
      "id": "00001003000000",
      "url": "/z/00001003000000",
      "meta": {...}
    },
    {
      "id": "00001004000000",
      "url": "/z/00001004000000",
      "meta": {...}
    },
    ...
    {
      "id": "00001014000000",
      "url": "/z/00001014000000",
      "meta": {...}
    }
  ]
}

Kind

The following top-level JSON keys are returned:

id
The zettel identifier for which the references were requested.
url
The API endpoint to fetch more information about the zettel.
meta:
The metadata of the zettel, encoded as a JSON object.
list
A list of JSON objects with keys id, url, and meta that describe other zettel in the defined order.

HTTP Status codes

200
Retrieval was successful, the body contains an appropriate JSON object.
400
Request was not valid.
403
You are not allowed to retrieve data of the given zettel.
404
Zettel not found. You probably used a zettel identifier that is not used in the Zettelstore.
  1. Metadata (key meta) are hidden to make the overall structure easier to read. ↩︎