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 cost, 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
. - Cost: a normal direct connection has cost 5, an indirect connection is the length of the shortest path between two zettel. The cost of a folgezettel or a precursor zettel is just 1, the cost of successor zettel and predecessor zettel are 2. You should limit the cost by using the parameter cost. Its default value is
17
. A value of0
does disable any cost 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&cost=5'
{"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.