((META (EMPTY-STRING title "API: List all zettel") (WORD role "manual") (TAG-SET tags ("#api" "#manual" "#zettelstore")) (WORD syntax "zmk") (ZID-SET back ("00001012000000")) (ZID-SET backward ("00001012000000" "00001012920000")) (NUMBER box-number "1") (STRING copyright "(c) 2020-present by Detlef Stern <ds@zettelstore.de>") (TIMESTAMP created "20210126175322") (ZID-SET folge ("00001012051400")) (ZID-SET forward ("00001006050000" "00001007700000" "00001007702000" "00001010040100" "00001010070200" "00001012050200" "00001012051400" "00001012920000" "00001012921200" "00001012930500")) (WORD lang "en") (EMPTY-STRING license "EUPL-1.2-or-later") (TIMESTAMP modified "20230807170810") (TIMESTAMP published "20230807170810") (WORD visibility "public")) (BLOCK (PARA (TEXT "To list all zettel just send a HTTP GET request to the ") (LINK-ZETTEL () "00001012920000" (TEXT "endpoint")) (TEXT " ") (LITERAL-INPUT () "/z") (ENDNOTE () (TEXT "If ") (LINK-ZETTEL () "00001010040100" (TEXT "authentication is enabled")) (TEXT ", you must include the a valid ") (LINK-ZETTEL () "00001012050200" (TEXT "access token")) (TEXT " in the ") (LITERAL-INPUT () "Authorization") (TEXT " header")) (TEXT ".") (SOFT) (TEXT "Always use the endpoint ") (LITERAL-INPUT () "/z") (TEXT " to work with a list of zettel.")) (PARA (TEXT "Without further specifications, a plain text document is returned, with one line per zettel.") (SOFT) (TEXT "Each line contains in the first 14 characters the ") (LINK-ZETTEL () "00001006050000" (TEXT "zettel identifier")) (TEXT ".") (SOFT) (TEXT "Separated by a space character, the title of the zettel follows:")) (VERBATIM-CODE (("" . "sh")) "# curl http://127.0.0.1:23123/z\n...\n00001012051200 API: List all zettel\n00001012050600 API: Provide an access token\n00001012050400 API: Renew an access token\n00001012050200 API: Authenticate a client\n...") (PARA (TEXT "The list is ") (FORMAT-STRONG () (TEXT "not")) (TEXT " sorted, even in the these examples where it appears to be sorted.") (SOFT) (TEXT "If you want to have it ordered, you must specify it with the help of a ") (LINK-ZETTEL () "00001007700000" (TEXT "query expression")) (TEXT " / ") (LINK-ZETTEL () "00001007702000" (TEXT "search term")) (TEXT ".") (SOFT) (TEXT "See ") (LINK-ZETTEL () "00001012051400" (TEXT "Query the list of all zettel")) (TEXT " how to do it.")) (HEADING 1 () "data-output" "data-output" (TEXT "Data output")) (PARA (TEXT "Alternatively, you may retrieve the zettel list as a parseable object / a ") (LINK-ZETTEL () "00001012930500" (TEXT "symbolic expression")) (TEXT " by providing the query parameter ") (LITERAL-INPUT () "enc=data") (TEXT ":")) (VERBATIM-CODE (("" . "sh")) "# curl 'http://127.0.0.1:23123/z?enc=data'\n(meta-list (query \"\") (human \"\") (list (zettel (id \"00001012921200\") (meta (title \"API: Encoding of Zettel Access Rights\") (role \"manual\") (tags \"#api #manual #reference #zettelstore\") (syntax \"zmk\") (back \"00001012051200 00001012051400 00001012053300 00001012053400 00001012053900 00001012054000\") (backward \"00001012051200 00001012051400 00001012053300 00001012053400 00001012053900 00001012054000\") (box-number \"1\") (created \"00010101000000\") (forward \"00001003000000 00001006020400 00001010000000 00001010040100 00001010040200 00001010070200 00001010070300\") (modified \"20220201171959\") (published \"20220201171959\")) (rights 62)) (zettel (id \"00001007030100\") ...") (PARA (TEXT "Pretty-printed, this results in:")) (VERBATIM-CODE () "(meta-list (query \"\")\n           (human \"\")\n           (list (zettel (id \"00001012921200\")\n                         (meta (title \"API: Encoding of Zettel Access Rights\")\n                               (role \"manual\")\n                               (tags \"#api #manual #reference #zettelstore\")\n                               (syntax \"zmk\")\n                               (back \"00001012051200 00001012051400 00001012053300 00001012053400 00001012053900 00001012054000\")\n                               (backward \"00001012051200 00001012051400 00001012053300 00001012053400 00001012053900 00001012054000\")\n                               (box-number \"1\")\n                               (created \"00010101000000\")\n                               (forward \"00001003000000 00001006020400 00001010000000 00001010040100 00001010040200 00001010070200 00001010070300\")\n                               (modified \"20220201171959\")\n                               (published \"20220201171959\"))\n                         (rights 62))\n                 (zettel (id \"00001007030100\")") (UNORDERED (INLINE (TEXT "The result is a list, starting with the symbol ") (LITERAL-INPUT () "meta-list") (TEXT ".")) (INLINE (TEXT "Then, some key/value pairs are following, also nested.")) (INLINE (TEXT "Keys ") (LITERAL-INPUT () "query") (TEXT " and ") (LITERAL-INPUT () "human") (TEXT " will be explained ") (LINK-ZETTEL () "00001012051400" (TEXT "later in this manual")) (TEXT ".")) (INLINE (LITERAL-INPUT () "list") (TEXT " starts a list of zettel.")) (INLINE (LITERAL-INPUT () "zettel") (TEXT " itself start, well, a zettel.")) (INLINE (LITERAL-INPUT () "id") (TEXT " denotes the zettel identifier, encoded as a string.")) (INLINE (TEXT "Nested in ") (LITERAL-INPUT () "meta") (TEXT " are the metadata, each as a key/value pair.")) (INLINE (LITERAL-INPUT () "rights") (TEXT " specifies the ") (LINK-ZETTEL () "00001012921200" (TEXT "access rights")) (TEXT " the user has for this zettel."))) (HEADING 1 () "note" "note" (TEXT "Note")) (PARA (TEXT "This request (and similar others) will always return a list of metadata, provided the request was syntactically correct.") (SOFT) (TEXT "There will never be a HTTP status code 403 (Forbidden), even if ") (LINK-ZETTEL () "00001010040100" (TEXT "authentication was enabled")) (TEXT " and you did not provide a valid access token.") (SOFT) (TEXT "In this case, the resulting list might be quite short (some zettel will have ") (LINK-ZETTEL () "00001010070200" (TEXT "public visibility")) (TEXT ") or the list might be empty.")) (PARA (TEXT "With this call, you cannot differentiate between an empty result list (e.g because your search did not found a zettel with the specified term) and an empty list because of missing authorization (e.g. an invalid access token).")) (HEADING 1 () "http-status-codes" "http-status-codes" (TEXT "HTTP Status codes")) (DESCRIPTION ((LITERAL-INPUT () "200")) (BLOCK (BLOCK (PARA (TEXT "Retrieval was successful, the body contains an appropriate data value.")))) ((LITERAL-INPUT () "400")) (BLOCK (BLOCK (PARA (TEXT "Request was not valid.") (HARD) (TEXT "There are several reasons for this.") (SOFT) (TEXT "Maybe the access bearer token was not valid.")))))))