API: Rename a zettel

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

Renaming a zettel is effectively just specifying a new identifier for the zettel. Since more than one box might contain a zettel with the old identifier, the rename operation must success in every relevant box to be overall successful. If the rename operation fails in one box, Zettelstore tries to rollback previous successful operations.

As a consequence, you cannot rename a zettel when its identifier is used in a read-only box. This applies to all predefined zettel, for example.

The endpoint to rename a zettel is /j/{ID}, where {ID} is a placeholder for the zettel identifier. You must send a HTTP MOVE request to this endpoint, and you must specify the new zettel identifier as an URL, placed under the HTTP request header key Destination.

# curl -X MOVE -H "Destination: 10000000000001"

Only the last 14 characters of the value of Destination are taken into account and those must form an unused zettel identifier. If the value contains less than 14 characters that do not form an unused zettel identifier, the response will contain a HTTP status code 400. All other characters, besides those 14 digits, are effectively ignored. However, the value should form a valid URL that could be used later to read the content of the freshly renamed zettel.

Alternatively, you can also use the endpoint /z/{ID}. Both endpoints behave identical.

HTTP Status codes

Rename was successful, there is no body in the response.
Request was not valid. For example, the HTTP header did not contain a valid Destination key, or the new identifier is already in use.
You are not allowed to delete the given zettel. In most cases you have either not enough access rights or at least one box containing the given identifier operates in read-only mode.
Zettel not found. You probably used a zettel identifier that is not used in the Zettelstore.

Rationale for the MOVE method

HTTP standardizes➚ eight methods. None of them is conceptually close to a rename operation.

Everyone is free to invent some new method to be used in HTTP. To avoid a divergency, there is a methods registry➚ that tracks those extensions. The HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)➚ defines the method MOVE that is quite close to the desired rename operation. In fact, some command line tools use a move method for renaming files.

Therefore, Zettelstore adopts somehow WebDAV's MOVE method and its use of the Destination HTTP header key.