Notecard Requests & Responses
The Notecard was designed with simplicity and ease of use as a fundamental goal. As such, the Notecard API exclusively consists of JSON requests to the Notecard and JSON responses from the Notecard. Notecard requests should be valid JSON. The argument list will vary by request type and usage.
{
"req": "<category.request>",
"argument-one": "value-one",
"argument-two": "value-two",
"argument-n": "value-n"
}
Format
Although usually allowed by JSON, newline characters (\n
) are not allowed
within a JSON request object because the Notecard API is based on
newline-delimited JSON (ndjson). In this documentation, JSON will be shown
with extra (invalid) newlines for human readability. When sending the
request, to the Notecard, it must be formatted with only a single \n
termination:
{"req":"<category.request>","argument-one":"value-one","argument-n":"value-n"}
\n
Requests
For each request, the req
field specifies the category (for example, hub
),
and request (for example, set
). In this example "req":"hub.set"
.
Important: Before you send a subsequent request to the Notecard, you must wait to receive the response from the previous request. It is unsafe to send a second request without waiting for the first to complete.
Responses
API Responses--also valid JSON--vary by request and are detailed
for each request in this document and in the
Complete API Reference. For all responses,
an err
field may be present in the returned object. If the err object is not
present in the Notecard response then no error has ocurred. Otherwise, the string
value will indicate the reason for the error.
The err
string is for developer consumption and is not intended for display
to end-users. For future-proof programmatic error handling, brace-delimited
keywords should be checked – for example, by searching for the string
"{connection-failure}"
within the err field in this sample response:
{
"err": "sync: unable to check for changes: {connection-failure} service disconnect"
}