API: Retrieve context of an existing zettel
The context of an origin zettel consists of those zettel that are somehow connected to the origin zettel. Direct connections of an origin zettel to other zettel are visible via metadata values, such as backward, forward or other values with type identifier or set of identifier.
The context is defined by a direction, a depth, and a limit:
- Direction: connections are directed.
For example, the metadata value of backward lists all zettel that link to the current zettel, while forward list all zettel to which the current zettel links to.
When you are only interested in one direction, set the parameter dir either to the value
backward
orforward
. All other values, including a missing value, is interpreted asboth
. - Depth: a direct connection has depth 1, an indirect connection is the length of the shortest path between two zettel.
You should limit the depth by using the parameter depth.
Its default value is
5
. A value of0
does disable any depth check. - Limit: to set an upper bound for the returned context, you should use the parameter limit.
Its default value is
200
. A value of0
disables does not limit the number of elements returned.
The search for the context of a zettel stops at the home zettel. This zettel is connected to all other zettel. If it is included, the context would become too big and therefore unusable.
To retrieve the context of an existing zettel, use the endpoint /x/{ID}1.
# curl 'http://127.0.0.1:23123/x/00001012053800?limit=3&dir=forward&depth=2'
{"id": "00001012053800","meta": {...},"rights":62,"list":[{"id": "00001012921000","meta": {...},"rights":62},{"id": "00001012920800","meta": {...},"rights":62},{"id": "00010000000000","meta": {...},"rights":62}]}
Formatted, this translates into:2
{
"id": "00001012053800",
"meta": {...},
"rights": 62,
"list": [
{
"id": "00001012921000",
"meta": {...},
"rights":62
},
{
"id": "00001012920800",
"meta": {...},
"rights":62
},
{
"id": "00010000000000",
"meta": {...},
"rights":62
}
]
}
Keys
The following top-level JSON keys are returned:
- id
- The zettel identifier for which the context was requested.
- meta:
- The metadata of the zettel, encoded as a JSON object.
- rights
- An integer number that describes the access rights for the given zettel.
- list
- A list of JSON objects with keys id, meta, and rights that contains the zettel of the context.
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.