API: Create a new zettel

A zettel is created by adding it to the list of zettel. Therefore, the endpoint to create a new zettel is also /z, but you must send the data of the new zettel via a HTTP POST request.

The zettel must be encoded in a plain format: first comes the metadata and the following content is separated by an empty line. This is the same format as used by storing zettel within a directory box.

# curl -X POST --data $'title: Note\n\nImportant content.' http://127.0.0.1:23123/z
20210903211500

The zettel identifier of the created zettel is returned. In addition, the HTTP response header contains a key Location with a relative URL for the new zettel. A client must prepend the HTTP protocol scheme, the host name, and (optional, but often needed) the post number to make it an absolute URL.

Alternatively, the body of the POST request may contain a JSON object that specifies metadata and content of the zettel to be created. To do this, you must add the query parameter enc=json. The following keys of the JSON object are used:

"meta"

References an embedded JSON object with only string values. The name/value pairs of this objects are interpreted as the metadata of the new zettel. Please consider the list of supported metadata keys (and their value types).

"encoding"

States how the content is encoded. Currently, only two values are allowed: the empty string ("") that specifies an empty encoding, and the string "base64" that specifies the standard Base64 encoding. Other values will result in a HTTP response status code 400.

"content"

Is a string value that contains the content of the zettel to be created. Typically, text content is not encoded, and binary content is encoded via Base64.

Other keys will be ignored. Even these three keys are just optional. The body of the HTTP POST request must not be empty and it must contain a JSON object.

Therefore, a body containing just {} is perfectly valid. The new zettel will have no content, and only an identifier as metadata:

# curl -X POST --data '{}' 'http://127.0.0.1:23123/z?enc=json'
{"id":"20210713161000"}

If creating the zettel was successful, the HTTP response will contain a JSON object with one key:

"id"

Contains the zettel identifier of the created zettel for further usage.

As an example, a zettel with title Note and content Important content. can be created by issuing:

# curl -X POST --data '{"meta":{"title":"Note"},"content":"Important content."}' 'http://127.0.0.1:23123/z?enc=json'
{"id":"20210713163100"}

HTTP Status codes

201

Zettel creation was successful, the body contains its zettel identifier (JSON object or plain text).

400

Request was not valid. There are several reasons for this. Most likely, the JSON was not formed according to above rules.

403

You are not allowed to create a new zettel.