API: Rename a zettel manual api manual zettelstore zmk 00001012000000 00001012000000 00001012920000 1 (c) 2020-present by Detlef Stern 20210713150005 00001004011200 00001005090000 00001006050000 00001010070600 00001012053300 00001012920000 en EUPL-1.2-or-later 20221219154659 20221219154659 public 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 /z/{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" http://127.0.0.1:23123/z/00001000000000 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. HTTP Status codes 204 Rename was successful, there is no body in the response. 400 Request was not valid. For example, the HTTP header did not contain a valid Destination key, or the new identifier is already in use. 403 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. 404 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.