title: API: Rename a zettel role: manual tags: #api #manual #zettelstore syntax: zmk back: 00001012000000 backward: 00001012000000 00001012920000 box-number: 1 copyright: (c) 2020-present by Detlef Stern created: 20210713150005 forward: 00001004011200 00001005090000 00001006050000 00001010070600 00001012053300 00001012920000 lang: en license: EUPL-1.2-or-later modified: 20221219154659 published: 20221219154659 visibility: public Renaming a zettel is effectively just specifying a new identifier for the zettel. Since more than one [[box|00001004011200]] 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|00001005090000]], for example. The [[endpoint|00001012920000]] to rename a zettel is ''/z/{ID}'', where ''{ID}'' is a placeholder for the [[zettel identifier|00001006050000]]. 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|00001006050000]]. 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|00001012053300]] 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|00001010070600]] 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|https://www.rfc-editor.org/rfc/rfc7231.txt]] 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|https://www.iana.org/assignments/http-methods/]] that tracks those extensions. The [[HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)|https://www.rfc-editor.org/rfc/rfc4918.txt]] 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.