(zettel (meta (back "00001005090000 00001012000000") (backward "00001005090000 00001012000000") (box-number "1") (created "20231128183917") (forward "00001006020100 00001012920000") (modified "20231128184701") (published "20231128184701") (role "manual") (syntax "zmk") (tags "#api #manual #zettelstore") (title "API: Determine a role zettel")) (rights 4) (encoding "") (content "The [[endpoint|00001012920000]] ''/z'' also allows you to determine a \"\"role zettel\"\", i.e. a zettel that documents a given role.\n\nThe query parameter \"\"''role''\"\" allows you to specify a value that is interpreted as the name of a role.\nZettelstore tries to determine the corresponding role zettel.\n\nA role zettel is a zettel with the [[''role''|00001006020100]] value \"\"role\"\" and a title that names the role.\nIf there is more than one zettel that qualifies, the zettel with the highest zettel identifier is used.\n\nFor example, if you want to determine the role zettel for the role \"\"manual\"\", your request will be:\n```sh\n# curl -i 'http://127.0.0.1:23123/z?role=manual'\nHTTP/1.1 302 Found\nContent-Type: text/plain; charset=utf-8\nLocation: /z/20231128184200\nContent-Length: 14\n\n20231128184200\n```\n\nIf there is a corresponding role zettel, the response will use the HTTP status code 302 (\"\"Found\"\"), the HTTP response header ''Location'' will contain the URL of the role zettel.\nIts zettel identifier will be returned in the HTTP response body.\n\nIf you specified some more query parameter, these will be part of the URL in the response header ''Location'':\n\n```sh\n# curl -i 'http://127.0.0.1:23123/z?role=manual&part=zettel'\nHTTP/1.1 302 Found\nContent-Type: text/plain; charset=utf-8\nLocation: /z/20231128184200?part=zettel\nContent-Length: 14\n\n20231128184200\n```\n\nOtherwise, if no role zettel was found, the response will use the HTTP status code 404 (\"\"Not found\"\").\n\n```sh\n# curl -i 'http://127.0.0.1:23123/z?role=norole'\nHTTP/1.1 404 Not Found\nContent-Type: text/plain; charset=utf-8\nContent-Length: 30\n\nRole zettel not found: norole\n```\n\nTo fulfill this service, Zettelstore will evaluate internally the query ''role:role title=ROLE'', there ''ROLE'' is the actual role.\n\nOf course, if you are only interested in the URL of the role zettel, you can make use of the HTTP ''HEAD'' method:\n\n```sh\n# curl -I 'http://127.0.0.1:23123/z?role=manual'\nHTTP/1.1 302 Found\nContent-Type: text/plain; charset=utf-8\nLocation: /z/20231128184200\nContent-Length: 14\n```\n\n=== HTTP Status codes\n; ''302''\n: Role zettel was found.\n  The HTTP header ''Location'' contains its URL, the body of the response contains its zettel identifier.\n; ''404''\n: No zettel for the given role was found."))