{"id":566,"date":"2024-06-27T13:10:38","date_gmt":"2024-06-27T13:10:38","guid":{"rendered":"https:\/\/developer.benify.com\/?page_id=566"},"modified":"2024-09-06T07:38:20","modified_gmt":"2024-09-06T07:38:20","slug":"queries","status":"publish","type":"page","link":"https:\/\/developer.benify.com\/queries\/","title":{"rendered":"Queries"},"content":{"rendered":"\t\t<div data-elementor-type=\"wp-page\" data-elementor-id=\"566\" class=\"elementor elementor-566\" data-elementor-post-type=\"page\">\n\t\t\t\t<div class=\"elementor-element elementor-element-ca819cb e-flex e-con-boxed e-con e-parent\" data-id=\"ca819cb\" data-element_type=\"container\">\n\t\t\t\t\t<div class=\"e-con-inner\">\n\t\t\t\t<div class=\"elementor-element elementor-element-b5b2e79 elementor-widget elementor-widget-heading\" data-id=\"b5b2e79\" data-element_type=\"widget\" data-widget_type=\"heading.default\">\n\t\t\t\t<div class=\"elementor-widget-container\">\n\t\t\t\t\t<h1 class=\"elementor-heading-title elementor-size-default\">Queries<\/h1>\t\t\t\t<\/div>\n\t\t\t\t<\/div>\n\t\t\t\t<div class=\"elementor-element elementor-element-51aa850 elementor-widget elementor-widget-text-editor\" data-id=\"51aa850\" data-element_type=\"widget\" data-widget_type=\"text-editor.default\">\n\t\t\t\t<div class=\"elementor-widget-container\">\n\t\t\t\t\t\t\t\t\t<p><span style=\"text-align: var(--text-align); font-size: 1rem; font-weight: 400;\">The query part of the URI is for refining and\/or modifying what is to be read or modified.<\/span><\/p><p data-renderer-start-pos=\"93\">The query consists of keys and\/or key-value pairs. Each key is either one of the defined attributes of the API or an attribute described below.<\/p><div class=\"ak-editor-panel cc-tqp4ke\" data-panel-type=\"warning\"><div class=\"ak-editor-panel__content\"><p data-renderer-start-pos=\"239\"><span style=\"color: #ff0000;\">An API <strong data-renderer-mark=\"true\">MUST<\/strong> return error code <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">400, Bad Request<\/code> if one or more of the keys are unrecognized.<\/span><\/p><\/div><\/div><h1>Introduction<\/h1><p data-renderer-start-pos=\"349\">Keys or key-values <strong data-renderer-mark=\"true\">MAY<\/strong> be used for:<\/p><ul class=\"ak-ul\" data-indent-level=\"1\"><li><p data-renderer-start-pos=\"388\">Selection of a subset of the resource<\/p><ul class=\"ak-ul\" data-indent-level=\"2\"><li><p data-renderer-start-pos=\"429\">on the items(<code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">id<\/code>&#8216;s) returned<\/p><\/li><li><p data-renderer-start-pos=\"468\">on the fields returned for each entry<\/p><\/li><\/ul><\/li><li><p data-renderer-start-pos=\"511\">Sorting of the resource (discouraged since it draws resources in the server, and is better done in the client)<\/p><\/li><li><p data-renderer-start-pos=\"625\">Pagination of the resource<\/p><\/li><li><p data-renderer-start-pos=\"703\">Selection of when in time the data to be used is valid (temporal selection)<\/p><\/li><li><p data-renderer-start-pos=\"782\">Selection of when in time the data to be used is written (temporal selection)<\/p><\/li><\/ul><p data-renderer-start-pos=\"863\">Multiple keys\/key-value-pairs <strong data-renderer-mark=\"true\">MAY<\/strong> be used in the same API call, separated by the ampersand (&#8220;&amp;&#8221;) character, and the result of such a call is that of all the supplied keys\/key-value-pairs used in an &#8220;AND&#8221; fashion. This means that an API call might look like: <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">...\/bicycles?size=28&amp;order=height:asc#...<\/code>, and will return all bicycles of size 28 ordered by height ascending.<\/p><p data-renderer-start-pos=\"1234\">NOTE: Following [<a class=\"cc-1rn59kg\" title=\"https:\/\/tools.ietf.org\/html\/rfc3986\" href=\"https:\/\/tools.ietf.org\/html\/rfc3986\" data-testid=\"link-with-safety\" data-renderer-mark=\"true\">RFC3986<\/a>], some characters are \u201creserved\u201d in a URI and <strong data-renderer-mark=\"true\">SHOULD <\/strong>be URL-encoded (the exceptions are \u201c-\u201d (hyphen), \u201c_\u201d (underscore), \u201c.\u201d (period), and \u201c~\u201d (tilde), and of course all characters and numbers). But when used in a query or fragment it is recommended for readability NOT to URL-encode where not necessary in order to increase readability. (The only exception is really the \u201c#\u201d (hash) in a query, since it breaks the query and starts the fragment. So if a value includes hashes, the hashes <strong data-renderer-mark=\"true\">MUST<\/strong> be URL-encoded.)<\/p><h2 id=\"_meta\" data-renderer-start-pos=\"1761\"><code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">_meta<\/code><\/h2><p data-renderer-start-pos=\"1761\">As a service to the client, a response to a query <strong data-renderer-mark=\"true\">SHOULD<\/strong> include metadata defining what query has been applied to the request. Such metadata <strong data-renderer-mark=\"true\">SHALL<\/strong> be part of the response, and <strong data-renderer-mark=\"true\">SHALL<\/strong> be a top level key-value consisting of the key <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">_meta<\/code> (note the leading underscore), and having an object of key-values as its value.<\/p><h1 id=\"Selection-queries\" data-renderer-start-pos=\"2115\">Selection queries<\/h1><p data-renderer-start-pos=\"2134\">Key-value-pairs can be used to select a subset of the resource based on item values: <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">...?size=24,28&amp;lights=on&amp;registered=true#...<\/code>.<\/p><p data-renderer-start-pos=\"2266\">There are two different ways of combining key-values; using <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">&amp;<\/code> (ampersand) or using <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">,<\/code> (comma). Their meanings are:<\/p><ul class=\"ak-ul\" data-indent-level=\"1\"><li><p data-renderer-start-pos=\"2383\"><code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">&amp;<\/code>: \u201cAnd\u201d. The result of the query is the result of the different parts \u201cand\u201ded together.<\/p><ul class=\"ak-ul\" data-indent-level=\"2\"><li><p data-renderer-start-pos=\"2475\">Example: <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">...?firstName=John&amp;lastName=Doe#...<\/code>. The result of the query are all the items having <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">firstname<\/code> equal to <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">Joe<\/code> <strong data-renderer-mark=\"true\">AND<\/strong> <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">lastName<\/code> equal to <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">Doe<\/code>.<\/p><\/li><\/ul><\/li><li><p data-renderer-start-pos=\"2626\"><code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">,<\/code>: \u201cOr\u201d. The result of the query is the result of the <strong data-renderer-mark=\"true\">same key<\/strong> having <em data-renderer-mark=\"true\">any of<\/em> the values in the comma-separated list.<\/p><ul class=\"ak-ul\" data-indent-level=\"2\"><li><p data-renderer-start-pos=\"2746\">It is semantically valid to use <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">&amp;<\/code> for OR\u2019ing values when the same key is repeated, ex: <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">...?firstName=John&amp;firstName=Jane&amp;...<\/code> since the AND\u2019ing of the same parameter (with different values) will otherwise result in the empty set. However, it is a bit counter-intuitive to use <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">&amp;<\/code> this way and therefore it is also accepted to use <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">,<\/code> for OR\u2019ing.<\/p><\/li><\/ul><\/li><\/ul><ul class=\"ak-ul\" data-indent-level=\"1\"><li><p data-renderer-start-pos=\"3101\">Example: <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">...?firstName=John,Jane&amp;lastName=Doe#...<\/code>. The result of the query are all the items having <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">firstname<\/code> equal to <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">Joe<\/code> <strong data-renderer-mark=\"true\">OR<\/strong> <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">firstname<\/code> equal to <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">Jane<\/code> &#8211; <strong data-renderer-mark=\"true\">AND<\/strong> <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">lastName<\/code> equal to <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">Doe<\/code>.<\/p><\/li><li><p data-renderer-start-pos=\"3283\">Note the precedence order: The <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">,<\/code> (<strong data-renderer-mark=\"true\">OR<\/strong>)&#8217;s are done <em data-renderer-mark=\"true\">before<\/em> any <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">&amp;<\/code> (<strong data-renderer-mark=\"true\">AND<\/strong>)&#8217;s.<\/p><\/li><\/ul><p data-renderer-start-pos=\"3357\">Note that he above does not let you specify \u201cI want all items with first name Jane <em data-renderer-mark=\"true\">or<\/em> last name Doe\u201d.<\/p><h2 id=\"When-can-a-selection-be-used?\" data-renderer-start-pos=\"3460\">When can a selection be used?<\/h2><p data-renderer-start-pos=\"3491\">Selection queries <strong data-renderer-mark=\"true\">MAY<\/strong> be used for <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">GET<\/code> (and hence also <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">HEAD<\/code>), <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">PATCH<\/code>, and <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">DELETE<\/code> methods on collections. Selection queries <strong data-renderer-mark=\"true\">MUST NOT<\/strong> be used for other methods.<\/p><h2 id=\"Error-returns\" data-renderer-start-pos=\"3649\">Error returns<\/h2><p data-renderer-start-pos=\"3664\">Using selection queries where prohibited <strong data-renderer-mark=\"true\">MUST<\/strong> return status code <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">400; Bad Request<\/code>.<\/p><p data-renderer-start-pos=\"3748\">Using modifiers that do not apply to a property <strong data-renderer-mark=\"true\">MUST<\/strong> return status code <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">400; Bad Request<\/code>.<\/p><h2 id=\"Examples\" data-renderer-start-pos=\"3839\">Examples<\/h2><p data-renderer-start-pos=\"3849\">The following selections <em data-renderer-mark=\"true\">are examples<\/em> of what can be used:<\/p><div class=\"pm-table-container with-shadow-observer\" data-layout=\"custom\"><div class=\"cc-12efcmn\">\u00a0<\/div><div class=\"pm-table-wrapper\"><div class=\"sentinel-left\">\u00a0<\/div><table data-testid=\"renderer-table\" data-number-column=\"false\" data-table-width=\"760\" data-layout=\"default\"><colgroup> <col \/> <col \/><\/colgroup><tbody><tr><th class=\"ak-renderer-tableHeader-sortable-column__wrapper\" colspan=\"1\" rowspan=\"1\" data-colwidth=\"380\" aria-sort=\"none\"><div class=\"ak-renderer-tableHeader-sortable-column\"><p data-renderer-start-pos=\"3912\"><strong data-renderer-mark=\"true\">Query<\/strong><\/p><\/div><\/th><th class=\"ak-renderer-tableHeader-sortable-column__wrapper\" colspan=\"1\" rowspan=\"1\" data-colwidth=\"380\" aria-sort=\"none\"><div class=\"ak-renderer-tableHeader-sortable-column\"><p data-renderer-start-pos=\"3921\"><strong data-renderer-mark=\"true\">Description<\/strong><\/p><\/div><\/th><\/tr><tr><td colspan=\"1\" rowspan=\"1\" data-colwidth=\"380\"><p data-renderer-start-pos=\"3938\">size=24,28<\/p><\/td><td colspan=\"1\" rowspan=\"1\" data-colwidth=\"380\"><p data-renderer-start-pos=\"3952\">The attribute exists and has <em data-renderer-mark=\"true\">one of<\/em> the specified values<\/p><\/td><\/tr><tr><td colspan=\"1\" rowspan=\"1\" data-colwidth=\"380\"><p data-renderer-start-pos=\"4014\">lights=on<\/p><\/td><td colspan=\"1\" rowspan=\"1\" data-colwidth=\"380\"><p data-renderer-start-pos=\"4027\">This is also valid for strings, booleans, enums, and so on<\/p><\/td><\/tr><tr><td colspan=\"1\" rowspan=\"1\" data-colwidth=\"380\"><p data-renderer-start-pos=\"4091\">registered<\/p><\/td><td colspan=\"1\" rowspan=\"1\" data-colwidth=\"380\"><p data-renderer-start-pos=\"4105\">The attribute exists<\/p><\/td><\/tr><tr><td colspan=\"1\" rowspan=\"1\" data-colwidth=\"380\"><p data-renderer-start-pos=\"4131\">fromDate=gt.2023-01-01T11:12:13<\/p><\/td><td colspan=\"1\" rowspan=\"1\" data-colwidth=\"380\"><p data-renderer-start-pos=\"4166\">\u201cgreater than\u201d (For more modifiers, see below)<\/p><\/td><\/tr><\/tbody><\/table><div class=\"sentinel-right\">\u00a0<\/div><\/div><\/div><h2 id=\"Different-ways-to-specify-selection-queries\" data-renderer-start-pos=\"4217\">Different ways to specify selection queries<\/h2><p data-renderer-start-pos=\"4262\">The selection queries are normally specified as part of the URL. However, there are situations when you do not want to expose data in the query, such as when you are requesting a selection based on sensitive information such as SSN. Therefore, selection queries can also be specified as a header field or in the body (our APIs can accept a body as part of a <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">GET<\/code> call, however that is nonstandard behavior). If supplied, then selection queries in both the header field <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">Query<\/code> and in the body are honored.<\/p><h2 id=\"Modifiers\" data-renderer-start-pos=\"4814\">Modifiers<\/h2><p data-renderer-start-pos=\"4825\">A modifier is a keyword modifying the selection by allowing for comparing a property to an open or closed range or a pattern, or to any other non-definitive value. This allows for comparing to a range of values, such as within a date range (which might be the typical use case).<\/p><p data-renderer-start-pos=\"5105\">A <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">.<\/code> (period) is used to separate the modifier from the value. If a modifier is unknown, it is treated as part of the value. (So, the query <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">...?qwe=asd.zxc&amp;...<\/code> does not treat <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">asd<\/code> as a modifier, but rather the whole <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">asd.zxc<\/code> is treated as the value that <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">qwe<\/code> is matched against)<\/p><p data-renderer-start-pos=\"5381\">Modifiers can be specified as below; also other types of ranges are allowed and <strong data-renderer-mark=\"true\">MUST<\/strong> be documented.<\/p><div class=\"pm-table-container with-shadow-observer\" data-layout=\"custom\"><div class=\"cc-12efcmn\">\u00a0<\/div><div class=\"pm-table-wrapper\"><div class=\"sentinel-left\">\u00a0<\/div><table data-testid=\"renderer-table\" data-number-column=\"false\" data-table-width=\"760\" data-layout=\"default\"><colgroup> <col \/> <col \/> <col \/><\/colgroup><tbody><tr><th class=\"ak-renderer-tableHeader-sortable-column__wrapper\" colspan=\"1\" rowspan=\"1\" data-colwidth=\"157\" aria-sort=\"none\"><div class=\"ak-renderer-tableHeader-sortable-column\"><p data-renderer-start-pos=\"5485\"><strong data-renderer-mark=\"true\">Modifier<\/strong><\/p><\/div><\/th><th class=\"ak-renderer-tableHeader-sortable-column__wrapper\" colspan=\"1\" rowspan=\"1\" data-colwidth=\"153\" aria-sort=\"none\"><div class=\"ak-renderer-tableHeader-sortable-column\"><p data-renderer-start-pos=\"5497\"><strong data-renderer-mark=\"true\">Data type<\/strong><\/p><\/div><\/th><th class=\"ak-renderer-tableHeader-sortable-column__wrapper\" colspan=\"1\" rowspan=\"1\" data-colwidth=\"450\" aria-sort=\"none\"><div class=\"ak-renderer-tableHeader-sortable-column\"><p data-renderer-start-pos=\"5510\"><strong data-renderer-mark=\"true\">Description<\/strong><\/p><\/div><\/th><\/tr><tr><td colspan=\"1\" rowspan=\"1\" data-colwidth=\"157\"><p data-renderer-start-pos=\"5527\">lt, le, ge, gt, ne<\/p><\/td><td colspan=\"1\" rowspan=\"1\" data-colwidth=\"153\"><p data-renderer-start-pos=\"5549\">Numeric \/ Time<\/p><\/td><td colspan=\"1\" rowspan=\"1\" data-colwidth=\"450\"><p data-renderer-start-pos=\"5567\">Less than, Less than or Equal, Greater then or Equal, Greater than, Not equal (Default, without a range, is \u201cEqual\u201d).<\/p><\/td><\/tr><tr><td colspan=\"1\" rowspan=\"1\" data-colwidth=\"157\"><p data-renderer-start-pos=\"5690\">lt, le, ge, gt, ne<\/p><\/td><td colspan=\"1\" rowspan=\"1\" data-colwidth=\"153\"><p data-renderer-start-pos=\"5712\">String<\/p><\/td><td colspan=\"1\" rowspan=\"1\" data-colwidth=\"450\"><p data-renderer-start-pos=\"5722\">Lexical string compare.<\/p><\/td><\/tr><tr><td colspan=\"1\" rowspan=\"1\" data-colwidth=\"157\"><p data-renderer-start-pos=\"5751\">~<\/p><\/td><td colspan=\"1\" rowspan=\"1\" data-colwidth=\"153\"><p data-renderer-start-pos=\"5756\">String<\/p><\/td><td colspan=\"1\" rowspan=\"1\" data-colwidth=\"450\"><p data-renderer-start-pos=\"5766\">Lexical string \u201ccontains\u201d (exact casing).<\/p><p data-renderer-start-pos=\"5809\">Ex: <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">~.red<\/code> matches <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">red<\/code> and <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">Fred<\/code> but not <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">Red<\/code> or <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">Reduce<\/code>.<\/p><\/td><\/tr><\/tbody><\/table><div class=\"sentinel-right\">\u00a0<\/div><\/div><\/div><h2 id=\"Response\" data-renderer-start-pos=\"5867\">Response<\/h2><p data-renderer-start-pos=\"5877\">The response <strong data-renderer-mark=\"true\">SHOULD<\/strong> include the selection as a key-value list:<\/p><div class=\"code-block cc-15qwbrk\"><p><span class=\"prismjs cc-1slwsjo\" data-code-lang=\"json\" data-ds--code--code-block=\"\" data-testid=\"renderer-code-block\"><code class=\"language-json\"><span class=\"\" data-testid=\"renderer-code-block-line-1\" data-ds--code--row=\"\"><span class=\"token punctuation\">{<\/span><br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-2\" data-ds--code--row=\"\">\u00a0 ...<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-3\" data-ds--code--row=\"\"><span class=\"token property\">\u00a0 \"_meta\"<\/span><span class=\"token operator\">:<\/span> <span class=\"token punctuation\">{<\/span><br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-4\" data-ds--code--row=\"\">\u00a0 \u00a0 ...<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-5\" data-ds--code--row=\"\"><span class=\"token property\">\u00a0 \u00a0 \"select\"<\/span><span class=\"token operator\">:<\/span> <span class=\"token punctuation\">{<\/span><br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-6\" data-ds--code--row=\"\"><span class=\"token property\">\u00a0 \u00a0 \u00a0 \"size\"<\/span><span class=\"token operator\">:<\/span> <span class=\"token punctuation\">[<\/span><span class=\"token number\">24<\/span><span class=\"token punctuation\">,<\/span> <span class=\"token number\">28<\/span><span class=\"token punctuation\">]<\/span><span class=\"token punctuation\">,<\/span><br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-7\" data-ds--code--row=\"\"><span class=\"token property\">\u00a0 \u00a0 \u00a0 \"lights\"<\/span><span class=\"token operator\">:<\/span> <span class=\"token string\">\"on\"<\/span><span class=\"token punctuation\">,<\/span><br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-8\" data-ds--code--row=\"\"><span class=\"token property\">\u00a0 \u00a0 \u00a0 \"isRegistered\"<\/span><span class=\"token operator\">:<\/span> <span class=\"token boolean\">true<\/span><span class=\"token punctuation\">,<\/span><br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-9\" data-ds--code--row=\"\"><span class=\"token property\">\u00a0 \u00a0 \u00a0 \"fromDate\"<\/span><span class=\"token operator\">:<\/span> <span class=\"token punctuation\">{<\/span> <span class=\"token property\">\"gt\"<\/span><span class=\"token operator\">:<\/span> <span class=\"token string\">\"2023-01-01T11:12:13\"<\/span> <span class=\"token punctuation\">}<\/span><br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-10\" data-ds--code--row=\"\"><span class=\"token punctuation\">\u00a0 \u00a0 }<\/span><br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-11\" data-ds--code--row=\"\">\u00a0 \u00a0 ...<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-12\" data-ds--code--row=\"\"><span class=\"token punctuation\">\u00a0 }<\/span><br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-13\" data-ds--code--row=\"\">\u00a0 ...<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-14\" data-ds--code--row=\"\"><span class=\"token punctuation\">}<\/span><\/span><\/code><\/span><\/p><\/div><p data-renderer-start-pos=\"6137\">For selections using <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">,<\/code> (<strong data-renderer-mark=\"true\">OR<\/strong>) the value for the select is an array of the values, For selections using modifiers the value is an object with the selector as the first argument and the value as the second.<\/p><div class=\"code-block cc-15qwbrk\"><p><span class=\"prismjs cc-1slwsjo\" data-code-lang=\"\" data-ds--code--code-block=\"\" data-testid=\"renderer-code-block\"><code class=\"language-\"><\/code><\/span><\/p><\/div><h1 id=\"Ordering-queries\" data-renderer-start-pos=\"7148\">Ordering queries<\/h1><p data-renderer-start-pos=\"7166\">Key-value pairs can be used to sort the results. Sorting is done as in the example: <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">...order=height:asc,length...<\/code>. This ordering orders the result according to the height property of the data. The meaning of &#8220;sorted in ascending order&#8221; is depending on the data type for the attribute. Multiple sort orders are separated by a comma (&#8220;,&#8221;). Orders <strong data-renderer-mark=\"true\">MAY<\/strong> be either ascending (denoted by the <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">asc<\/code> keyword) or descending (denoted by the <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">desc<\/code> keyword). If specified, <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">asc<\/code> or <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">desc<\/code> <strong data-renderer-mark=\"true\">MUST<\/strong> be separated from the property by a colon character (<code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">:<\/code>). If not specified the <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">asc<\/code> ordering is assumed.<\/p><p data-renderer-start-pos=\"7744\">Ordering queries <strong data-renderer-mark=\"true\">MAY<\/strong> be used for the <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">GET<\/code> (and hence also <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">HEAD<\/code>) method. Ordering queries <strong data-renderer-mark=\"true\">MUST NOT<\/strong> be used for other methods.<\/p><h2 id=\"Error-returns.1\" data-renderer-start-pos=\"7869\">Error returns<\/h2><p data-renderer-start-pos=\"7884\">Using ordering queries where prohibited <strong data-renderer-mark=\"true\">MUST<\/strong> return status code <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">400; Bad Request<\/code>.<\/p><p data-renderer-start-pos=\"7967\">Using a ordering query specifying an attribute that does not exist <strong data-renderer-mark=\"true\">MUST<\/strong> return status code <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">400; Bad Request<\/code>.<\/p><p data-renderer-start-pos=\"8077\">Using multiple <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">order<\/code> keys (<code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">...&amp;order=height:asc&amp;order=length&amp;...<\/code>) is not allowed and <strong data-renderer-mark=\"true\">MUST<\/strong> return status code <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">400; Bad Request<\/code>.<\/p><h2 id=\"Response.1\" data-renderer-start-pos=\"8205\">Response<\/h2><p data-renderer-start-pos=\"8215\">The response <strong data-renderer-mark=\"true\">SHOULD<\/strong> include the ordering as an array where the order of the elements are the sort order, and the columns sorted on is followed by a colon and the sort order (<code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">asc<\/code> or <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">desc<\/code>).<\/p><div class=\"code-block cc-15qwbrk\"><p><span class=\"prismjs cc-1slwsjo\" data-code-lang=\"\" data-ds--code--code-block=\"\" data-testid=\"renderer-code-block\"><code class=\"language-\"><span class=\"\" data-testid=\"renderer-code-block-line-1\" data-ds--code--row=\"\">{<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-2\" data-ds--code--row=\"\">\u00a0 ...<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-3\" data-ds--code--row=\"\">\u00a0 \"_meta\": {<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-4\" data-ds--code--row=\"\">\u00a0 \u00a0 ...<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-5\" data-ds--code--row=\"\">\u00a0 \u00a0 \"order\": [<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-6\" data-ds--code--row=\"\">\u00a0 \u00a0 \u00a0 { \"height\": \"asc\" },<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-7\" data-ds--code--row=\"\">\u00a0 \u00a0 \u00a0 { \"length\": \"asc\" }<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-8\" data-ds--code--row=\"\">\u00a0 \u00a0 ]<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-9\" data-ds--code--row=\"\">\u00a0 \u00a0...<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-10\" data-ds--code--row=\"\">\u00a0 }<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-11\" data-ds--code--row=\"\">\u00a0 ...<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-12\" data-ds--code--row=\"\">}<\/span><\/code><\/span><\/p><\/div><p data-renderer-start-pos=\"8528\">Note: Question: Why an array? Wouldn&#8217;t an ordered list of key-values be better? Answer: An array is guaranteed to maintain order, whereas key-values are not. So in the latter case the sort order might be permuted.<\/p><h1 id=\"Range-queries\" data-renderer-start-pos=\"8874\">Range queries<\/h1><p data-renderer-start-pos=\"8889\">Query parameters can be used to select a range of entries being returned.<\/p><p data-renderer-start-pos=\"8964\">There are different ways of defining a range; one could say &#8220;Page size is 20 &amp; give me page 3&#8221; (page-based), or &#8220;return entries 40 to 59&#8221; (item-based) &#8211; both yield the same result (if using zero based counting). Another way of specifying a range is to use server based cursors, but we are not supporting that (yet).<\/p><p data-renderer-start-pos=\"9361\">It is up to the API to decide what range query method to support; it <strong data-renderer-mark=\"true\">SHOULD<\/strong> be documented in the API specification.<\/p><p data-renderer-start-pos=\"9478\">Ranging queries <strong data-renderer-mark=\"true\">MAY<\/strong> be used for the <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">GET<\/code> (and hence also <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">HEAD<\/code>) method. Paging queries <strong data-renderer-mark=\"true\">MUST NOT<\/strong> be used for other methods.<\/p><p data-renderer-start-pos=\"9600\"><strong data-renderer-mark=\"true\">NOTE<\/strong>: If a partial response query is used in conjunction with an ordering and\/or selection query, it is the list of items <em data-renderer-mark=\"true\">after<\/em> applying the ordering and\/or selection query that is subject to ranging!<\/p><h3 id=\"Errors\" data-renderer-start-pos=\"9802\">Errors<\/h3><p data-renderer-start-pos=\"9810\">Using range queries where prohibited <strong data-renderer-mark=\"true\">MUST<\/strong> return status code <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">400; Bad Request<\/code>.<\/p><p data-renderer-start-pos=\"9890\">Only one range query method (from the below) <strong data-renderer-mark=\"true\">MAY<\/strong> be specified; else status code <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">400; Bad Request<\/code> will be returned.<\/p><h2 id=\"Page-based\" data-renderer-start-pos=\"10006\">Page-based<\/h2><p data-renderer-start-pos=\"10018\">Page-based range <strong data-renderer-mark=\"true\">SHOULD<\/strong> use the format <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">\"...page=&lt;#&gt;&amp;pageSize=&lt;#&gt;...\"<\/code> where both <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">page<\/code> and <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">pageSize<\/code> are inclusive and with zero-based indexing.<\/p><h4 id=\"Errors.1\" data-renderer-start-pos=\"10161\">Errors<\/h4><p data-renderer-start-pos=\"10169\">A page-based query where either value is not a positive number <strong data-renderer-mark=\"true\">MUST<\/strong> return status code <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">400; Bad Request<\/code>.<\/p><h4 id=\"Response.2\" data-renderer-start-pos=\"10275\">Response<\/h4><p data-renderer-start-pos=\"10285\">The response <strong data-renderer-mark=\"true\">SHOULD<\/strong> include the following information:<\/p><div class=\"code-block cc-15qwbrk\"><p><span class=\"prismjs cc-1slwsjo\" data-code-lang=\"\" data-ds--code--code-block=\"\" data-testid=\"renderer-code-block\"><code class=\"language-\"><span class=\"\" data-testid=\"renderer-code-block-line-1\" data-ds--code--row=\"\">{<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-2\" data-ds--code--row=\"\">\u00a0 ...<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-3\" data-ds--code--row=\"\">\u00a0 \"_meta\": {<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-4\" data-ds--code--row=\"\">\u00a0 \u00a0 ...<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-5\" data-ds--code--row=\"\">\u00a0 \u00a0 \"page\": {<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-6\" data-ds--code--row=\"\">\u00a0 \u00a0 \u00a0 \"page\": &lt;#&gt;,<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-7\" data-ds--code--row=\"\">\u00a0 \u00a0 \u00a0 \"pageSize\": &lt;#&gt;,<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-8\" data-ds--code--row=\"\">\u00a0 \u00a0 },<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-9\" data-ds--code--row=\"\">\u00a0 \u00a0 \"count\": &lt;#&gt;,<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-10\" data-ds--code--row=\"\">\u00a0 \u00a0 ...<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-11\" data-ds--code--row=\"\">\u00a0 }<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-12\" data-ds--code--row=\"\">\u00a0 ...<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-13\" data-ds--code--row=\"\">}<\/span><\/code><\/span><\/p><\/div><p data-renderer-start-pos=\"10472\">where <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">page<\/code> and <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">pageSize<\/code> are echoing the parameters sent in the request and <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">count<\/code> is the actual number of items returned.<\/p><h2 id=\"Index-based\" data-renderer-start-pos=\"10785\">Index-based<\/h2><p data-renderer-start-pos=\"10798\">Index-based range <strong data-renderer-mark=\"true\">SHOULD<\/strong> use the format <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">\"...from=&lt;#&gt;&amp;to=&lt;#&gt;...\"<\/code> where both from and to are inclusive and with zero-based indexing.<\/p><h2 id=\"Errors.2\" data-renderer-start-pos=\"10930\">Errors<\/h2><p data-renderer-start-pos=\"10938\">An index-based range where either value is not a positive number <strong data-renderer-mark=\"true\">MUST<\/strong> return status code <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">400; Bad Request<\/code>.<\/p><p data-renderer-start-pos=\"11046\">Using an item-based range where <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">from<\/code> &gt; <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">to<\/code> <strong data-renderer-mark=\"true\">MUST<\/strong> return status code <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">400; Bad Request<\/code>. If, however, <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">from<\/code> &gt; maximum index, or <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">to<\/code> &lt; minimum index, then <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">404; Not Found<\/code> <strong data-renderer-mark=\"true\">MUST<\/strong> be returned.<\/p><h2 id=\"Response.3\" data-renderer-start-pos=\"11227\">Response<\/h2><p data-renderer-start-pos=\"11237\">The response <strong data-renderer-mark=\"true\">SHOULD<\/strong> include the following information:<\/p><div class=\"code-block cc-15qwbrk\"><p><span class=\"prismjs cc-1slwsjo\" data-code-lang=\"\" data-ds--code--code-block=\"\" data-testid=\"renderer-code-block\"><code class=\"language-\"><span class=\"\" data-testid=\"renderer-code-block-line-1\" data-ds--code--row=\"\">{<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-2\" data-ds--code--row=\"\">\u00a0 ...<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-3\" data-ds--code--row=\"\">\u00a0 \"_meta\": {<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-4\" data-ds--code--row=\"\">\u00a0 \u00a0 ...<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-5\" data-ds--code--row=\"\">\u00a0 \u00a0 \"index\": {<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-6\" data-ds--code--row=\"\">\u00a0 \u00a0 \u00a0 \"from\": &lt;#&gt;,<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-7\" data-ds--code--row=\"\">\u00a0 \u00a0 \u00a0 \"to\": &lt;#&gt;<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-8\" data-ds--code--row=\"\">\u00a0 \u00a0 },<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-9\" data-ds--code--row=\"\">\u00a0 \u00a0 \"count\": &lt;#&gt;,<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-10\" data-ds--code--row=\"\">\u00a0 \u00a0 ...<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-11\" data-ds--code--row=\"\">\u00a0 }<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-12\" data-ds--code--row=\"\">\u00a0 ...<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-13\" data-ds--code--row=\"\">}<\/span><\/code><\/span><\/p><\/div><p data-renderer-start-pos=\"11420\">where <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">from<\/code> and <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">to<\/code> are echoing the parameters sent in the request and <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">count<\/code> is the actual number of items returned.<\/p><h1>Field selection<\/h1><p data-renderer-start-pos=\"11740\">The field selection query selects which fields are to be returned. Using this, it is possible to select which fields are to be returned, so that not the whole object(s) is returned when only a few fields are needed.<\/p><p data-renderer-start-pos=\"11957\">An API may define which fields are available for field selection, and it <strong data-renderer-mark=\"true\">MAY<\/strong> be none (not accepting field selection) or a subset of the fields available. This <strong data-renderer-mark=\"true\">SHALL<\/strong> be documented for each API path\/method.<\/p><p data-renderer-start-pos=\"12179\">Field selection is done as in the example: <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">...fields=id,address...<\/code> where the key <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">fields<\/code> only appear once in the query and the fields selected (if multiple) are separated by a comma (\u201c<code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">,<\/code>&#8220;).<\/p><p data-renderer-start-pos=\"12368\">Multiple <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">fields<\/code> keys in the query is an error and <strong data-renderer-mark=\"true\">MUST<\/strong> return 400, Bad Request.<\/p><p data-renderer-start-pos=\"12449\">Unrecognized field names in the query value is an error and <strong data-renderer-mark=\"true\">MUST<\/strong> return 400, Bad Request.<\/p><h2 id=\"Response.4\" data-renderer-start-pos=\"12540\">Response<\/h2><p data-renderer-start-pos=\"12550\">The response <strong data-renderer-mark=\"true\">SHOULD<\/strong> include the following information:<\/p><div class=\"code-block cc-15qwbrk\"><p><span class=\"prismjs cc-1slwsjo\" data-code-lang=\"\" data-ds--code--code-block=\"\" data-testid=\"renderer-code-block\"><code class=\"language-\"><span class=\"\" data-testid=\"renderer-code-block-line-1\" data-ds--code--row=\"\">{<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-2\" data-ds--code--row=\"\">\u00a0 ...<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-3\" data-ds--code--row=\"\">\u00a0 \"_meta\": {<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-4\" data-ds--code--row=\"\">\u00a0 \u00a0 ...<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-5\" data-ds--code--row=\"\">\u00a0 \u00a0 \"fields\": [<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-6\" data-ds--code--row=\"\">\u00a0 \u00a0 \u00a0 \"fieldname\",<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-7\" data-ds--code--row=\"\">\u00a0 \u00a0 \u00a0 \"fieldname\",<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-8\" data-ds--code--row=\"\">\u00a0 \u00a0 \u00a0 ...<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-9\" data-ds--code--row=\"\">\u00a0 \u00a0 ],<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-10\" data-ds--code--row=\"\">\u00a0 \u00a0 ...<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-11\" data-ds--code--row=\"\">\u00a0 }<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-12\" data-ds--code--row=\"\">\u00a0 ...<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-13\" data-ds--code--row=\"\">}<\/span><\/code><\/span><\/p><\/div><h1 data-renderer-start-pos=\"12727\">Historic data<\/h1><p>There are two ways to request historic data &#8211; asOf and asAt.<\/p><h2 id=\"Data-as-valid-at-a-point-in-time----asOf\" data-renderer-start-pos=\"12727\">Data as valid at a point in time &#8211; asOf<\/h2><p data-renderer-start-pos=\"12769\">To select a specific temporal instance of the data, based on the semantics of the data, the selector <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">asOf<\/code> can be used.<\/p><p data-renderer-start-pos=\"12889\">The temporal selector is done as: <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">...?asOf=&lt;datetime&gt;&amp;...<\/code>, where the value <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">datetime<\/code> is a Date-Time or Timestamp value.<\/p><p data-renderer-start-pos=\"13053\">This keyword is used to get the data <em data-renderer-mark=\"true\">valid <strong data-renderer-mark=\"true\">for<\/strong> a specific point in time<\/em>. Example: Let\u2019s say you have a field named \u201ctitle\u201d. A person has the title \u201cSales Rep\u201d, but on Mar 1<sup data-renderer-mark=\"true\">st<\/sup> that person is promoted to \u201cSr. Sales Rep\u201c. However, the change in the HR system is not done until Mar 5<sup data-renderer-mark=\"true\">th<\/sup>, but the validity date for that title change is set to Mar 1<sup data-renderer-mark=\"true\">st<\/sup>. Now, to get the data valid <em data-renderer-mark=\"true\">as of<\/em> Mar 1<sup data-renderer-mark=\"true\">st<\/sup>, the selector <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">...?asOf=&lt;datetime&gt;&amp;...<\/code> can be used! If that request is sent om Mar 4<sup data-renderer-mark=\"true\">th<\/sup>, the result would be \u201cSales Rep\u201d, but for the same request sent on Mar 6<sup data-renderer-mark=\"true\">th<\/sup>, the result would be \u201cSr. Sales Rep\u201d!<\/p><p data-renderer-start-pos=\"13640\">A common pattern for the semantics of <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">asOf<\/code> is to have the first instance of the data valid <em data-renderer-mark=\"true\">as of<\/em> any point in time. Later updates to the data might then include a date-time or a date from which that data is valid, and that date-time\/date might very well be in the past.<\/p><p data-renderer-start-pos=\"13911\"><strong data-renderer-mark=\"true\">Note<\/strong>: It is up to each API to define which field is used for the <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">asOf<\/code> selector.<\/p><h2 id=\"Errors.3\" data-renderer-start-pos=\"13992\">Errors<\/h2><p data-renderer-start-pos=\"14000\">A value that does not evaluate to a date-time or timestamp is an error and <strong data-renderer-mark=\"true\">MUST<\/strong> return 400, Bad Request. Multiple <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">asOf<\/code> selectors is an error and <strong data-renderer-mark=\"true\">MUST<\/strong> return 400, Bad Request.<\/p><h2 id=\"Response.5\" data-renderer-start-pos=\"14176\">Response<\/h2><p data-renderer-start-pos=\"14186\">The response <strong data-renderer-mark=\"true\">SHOULD<\/strong> include the following information:<\/p><div class=\"code-block cc-15qwbrk\"><p><span class=\"prismjs cc-1es5wws\" data-code-lang=\"\" data-ds--code--code-block=\"\" data-testid=\"renderer-code-block\"><code class=\"language-\"><span class=\"\" data-testid=\"renderer-code-block-line-1\" data-ds--code--row=\"\">{<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-2\" data-ds--code--row=\"\">\u00a0 ...<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-3\" data-ds--code--row=\"\">\u00a0 \"_meta\": {<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-4\" data-ds--code--row=\"\">\u00a0 \u00a0 ...<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-5\" data-ds--code--row=\"\">\u00a0 \u00a0 \"asOf\": \"date-time\",<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-6\" data-ds--code--row=\"\">\u00a0 \u00a0 ...<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-7\" data-ds--code--row=\"\">\u00a0 }<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-8\" data-ds--code--row=\"\">\u00a0 ...<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-9\" data-ds--code--row=\"\">}<\/span><\/code><\/span><\/p><\/div><h2 id=\"Data-as-written-at-a-point-in-time----asAt\" data-renderer-start-pos=\"14317\">Data as written at a point in time &#8211; asAt<\/h2><p data-renderer-start-pos=\"14361\">To select a specific temporal instance of the data, based on the \u201cwrite timestamp\u201d of the data, the selector <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">asAt<\/code> can be used.<\/p><p data-renderer-start-pos=\"14484\">The temporal selector is done as: <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">...?asAt=&lt;datetime&gt;&amp;...<\/code>, where the value <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">datetime<\/code> is a Date-Time or Timestamp value.<\/p><p data-renderer-start-pos=\"14648\">This keyword is used to get the data <em data-renderer-mark=\"true\">valid <strong data-renderer-mark=\"true\">at<\/strong> a specific point in time<\/em>. Example: Let\u2019s say you have a field named \u201ctitle\u201d. A person has the title \u201cSales Rep\u201d, but on Mar 1<sup data-renderer-mark=\"true\">st<\/sup> that person is promoted to \u201cSr. Sales Rep\u201c. However, the change in the HR system is not done until Mar 5<sup data-renderer-mark=\"true\">th<\/sup>, but the validity date for that title change is set to Mar 1<sup data-renderer-mark=\"true\">st<\/sup>. Now, to get the data valid <em data-renderer-mark=\"true\">as it was written at<\/em> Mar 1<sup data-renderer-mark=\"true\">st<\/sup>, the selector <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">...?asAt=&lt;datetime&gt;&amp;...<\/code> can be used! If that request is sent om Mar 4<sup data-renderer-mark=\"true\">th<\/sup>, the result would be \u201cSales Rep\u201d, and for the same request sent on Mar 6<sup data-renderer-mark=\"true\">th<\/sup>, the result would <em data-renderer-mark=\"true\">still<\/em> be \u201cSales Rep\u201d!<\/p><h2 id=\"Errors.4\" data-renderer-start-pos=\"15251\">Errors<\/h2><p data-renderer-start-pos=\"15259\">A value that does not evaluate to a date-time or timestamp is an error and <strong data-renderer-mark=\"true\">MUST<\/strong> return 400, Bad Request. Multiple <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">asAt<\/code> selectors is an error and <strong data-renderer-mark=\"true\">MUST<\/strong> return 400, Bad Request.<\/p><h2 id=\"Response.6\" data-renderer-start-pos=\"15435\">Response<\/h2><p data-renderer-start-pos=\"15445\">The response <strong data-renderer-mark=\"true\">SHOULD<\/strong> include the following information:<\/p><div class=\"code-block cc-15qwbrk\"><p><span class=\"prismjs cc-1es5wws\" data-code-lang=\"\" data-ds--code--code-block=\"\" data-testid=\"renderer-code-block\"><code class=\"language-\"><span class=\"\" data-testid=\"renderer-code-block-line-1\" data-ds--code--row=\"\">{<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-2\" data-ds--code--row=\"\">\u00a0 ...<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-3\" data-ds--code--row=\"\">\u00a0 \"_meta\": {<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-4\" data-ds--code--row=\"\">\u00a0 \u00a0 ...<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-5\" data-ds--code--row=\"\">\u00a0 \u00a0 \"asAt\": \"date-time\",<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-6\" data-ds--code--row=\"\">\u00a0 \u00a0 ...<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-7\" data-ds--code--row=\"\">\u00a0 }<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-8\" data-ds--code--row=\"\">\u00a0 ...<br \/><\/span><span class=\"\" data-testid=\"renderer-code-block-line-9\" data-ds--code--row=\"\">}<\/span><\/code><\/span><\/p><\/div><h2 id=\"Difference-between-asOf-and-asAt\" data-renderer-start-pos=\"15576\">Difference between <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">asOf<\/code> and <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">asAt<\/code><\/h2><p data-renderer-start-pos=\"15576\">In this example, <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">asOf<\/code> is depending on the field <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">thingUpdated<\/code>. It is of type <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">date-time<\/code> and is <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">nullable<\/code>. (A <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">null<\/code> value is normally treated as \u201csince epoch\u201d, but this is API dependent.)<\/p><p data-renderer-start-pos=\"15797\">As you can see in the example, asking for <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">asOf<\/code> returns the data as valid for that <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">date-time<\/code> based on the value of the field <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">thingUpdated<\/code>, whereas asking for <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">asAt<\/code> returns the value as it existed at that <code class=\"code cc-1o5d2cw\" data-renderer-mark=\"true\">date-time<\/code>.<\/p><div class=\"ak-renderer-extension \" data-layout=\"default\"><div class=\"ak-renderer-extension-overflow-container\"><div class=\"css-13i783a ey937e10\" data-fabric-macro=\"810b6433-428a-4201-9968-75fca1fa47df\" data-macro-body=\"\" data-macro-parameters=\"{&quot;zoom&quot;:&quot;1&quot;,&quot;simple&quot;:&quot;0&quot;,&quot;custContentId&quot;:&quot;11514413103&quot;,&quot;pageId&quot;:&quot;11500158979&quot;,&quot;lbox&quot;:&quot;1&quot;,&quot;diagramDisplayName&quot;:&quot;asOf-asAt&quot;,&quot;hiResPreview&quot;:&quot;0&quot;,&quot;baseUrl&quot;:&quot;https:\/\/benify.atlassian.net\/wiki&quot;,&quot;imgPageId&quot;:&quot;10901913616&quot;,&quot;diagramName&quot;:&quot;asOf-asAt&quot;,&quot;pCenter&quot;:&quot;0&quot;,&quot;aspect&quot;:&quot;rk9hxL99Q7_id3wSGRAG 1&quot;,&quot;width&quot;:&quot;769&quot;,&quot;includedDiagram&quot;:&quot;1&quot;,&quot;aspectHash&quot;:&quot;fe01fd92e9053654a6b50d8cf48063ca327ee549&quot;,&quot;links&quot;:&quot;auto&quot;,&quot;tbstyle&quot;:&quot;top&quot;,&quot;height&quot;:&quot;525&quot;}\" data-testid=\"legacy-macro-element\"><div id=\"ap-com.mxgraph.confluence.plugins.diagramly__inc-drawio5447159607677367553\" class=\"ap-container conf-macro output-block\" data-hasbody=\"false\" data-local-id=\"beda29d2-17b4-4008-abb2-d3973eef69e7\" data-macro-id=\"810b6433-428a-4201-9968-75fca1fa47df\" data-macro-name=\"inc-drawio\"><div id=\"embedded-com.mxgraph.confluence.plugins.diagramly__inc-drawio5447159607677367553\" class=\"ap-content \"><div id=\"embedded-com.mxgraph.confluence.plugins.diagramly__inc-drawio__1e283ee5\" class=\"ap-iframe-container iframe-init\">\u00a0<\/div><\/div><\/div><\/div><\/div><\/div>\t\t\t\t\t\t\t\t<\/div>\n\t\t\t\t<\/div>\n\t\t\t\t<div class=\"elementor-element elementor-element-3a67bc3 elementor-widget elementor-widget-image\" data-id=\"3a67bc3\" data-element_type=\"widget\" data-widget_type=\"image.default\">\n\t\t\t\t<div class=\"elementor-widget-container\">\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t<img data-recalc-dims=\"1\" fetchpriority=\"high\" decoding=\"async\" width=\"779\" height=\"535\" src=\"https:\/\/i0.wp.com\/epa3f9ne4af.exactdn.com\/wp-content\/uploads\/asOf-asAtpng.png?resize=779%2C535&#038;ssl=1\" class=\"attachment-large size-large wp-image-568\" alt=\"\" srcset=\"https:\/\/i0.wp.com\/developer.benify.com\/wp-content\/uploads\/asOf-asAtpng.png?w=779&amp;ssl=1 779w, https:\/\/i0.wp.com\/developer.benify.com\/wp-content\/uploads\/asOf-asAtpng.png?resize=300%2C206&amp;ssl=1 300w, https:\/\/i0.wp.com\/developer.benify.com\/wp-content\/uploads\/asOf-asAtpng.png?resize=768%2C527&amp;ssl=1 768w\" sizes=\"(max-width: 779px) 100vw, 779px\" \/>\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t<\/div>\n\t\t\t\t<\/div>\n\t\t\t\t\t<\/div>\n\t\t\t\t<\/div>\n\t\t\t\t<\/div>\n\t\t","protected":false},"excerpt":{"rendered":"<p>Queries The query part of the URI is for refining and\/or modifying what is to be read or modified. The query consists of keys and\/or key-value pairs. Each key is either one of the defined attributes of the API or an attribute described below. An API MUST return error code 400, Bad Request if one [&hellip;]<\/p>\n","protected":false},"author":3,"featured_media":0,"parent":0,"menu_order":0,"comment_status":"closed","ping_status":"closed","template":"","meta":{"nf_dc_page":"","footnotes":""},"class_list":["post-566","page","type-page","status-publish","hentry"],"yoast_head":"<!-- This site is optimized with the Yoast SEO Premium plugin v26.4 (Yoast SEO v27.4) - https:\/\/yoast.com\/product\/yoast-seo-premium-wordpress\/ -->\n<title>Queries - Benify Developer Portal<\/title>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/developer.benify.com\/queries\/\" \/>\n<meta property=\"og:locale\" content=\"en_US\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"Queries\" \/>\n<meta property=\"og:description\" content=\"Queries The query part of the URI is for refining and\/or modifying what is to be read or modified. The query consists of keys and\/or key-value pairs. Each key is either one of the defined attributes of the API or an attribute described below. An API MUST return error code 400, Bad Request if one [&hellip;]\" \/>\n<meta property=\"og:url\" content=\"https:\/\/developer.benify.com\/queries\/\" \/>\n<meta property=\"og:site_name\" content=\"Benify Developer Portal\" \/>\n<meta property=\"article:modified_time\" content=\"2024-09-06T07:38:20+00:00\" \/>\n<meta property=\"og:image\" content=\"https:\/\/developer.benify.com\/wp-content\/uploads\/asOf-asAtpng.png\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:label1\" content=\"Est. reading time\" \/>\n\t<meta name=\"twitter:data1\" content=\"12 minutes\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\\\/\\\/schema.org\",\"@graph\":[{\"@type\":\"WebPage\",\"@id\":\"https:\\\/\\\/developer.benify.com\\\/queries\\\/\",\"url\":\"https:\\\/\\\/developer.benify.com\\\/queries\\\/\",\"name\":\"Queries - Benify Developer Portal\",\"isPartOf\":{\"@id\":\"https:\\\/\\\/developer.benify.com\\\/#website\"},\"primaryImageOfPage\":{\"@id\":\"https:\\\/\\\/developer.benify.com\\\/queries\\\/#primaryimage\"},\"image\":{\"@id\":\"https:\\\/\\\/developer.benify.com\\\/queries\\\/#primaryimage\"},\"thumbnailUrl\":\"https:\\\/\\\/developer.benify.com\\\/wp-content\\\/uploads\\\/asOf-asAtpng.png\",\"datePublished\":\"2024-06-27T13:10:38+00:00\",\"dateModified\":\"2024-09-06T07:38:20+00:00\",\"breadcrumb\":{\"@id\":\"https:\\\/\\\/developer.benify.com\\\/queries\\\/#breadcrumb\"},\"inLanguage\":\"en-US\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\\\/\\\/developer.benify.com\\\/queries\\\/\"]}]},{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\\\/\\\/developer.benify.com\\\/queries\\\/#primaryimage\",\"url\":\"https:\\\/\\\/epa3f9ne4af.exactdn.com\\\/wp-content\\\/uploads\\\/asOf-asAtpng.png?strip=all\",\"contentUrl\":\"https:\\\/\\\/epa3f9ne4af.exactdn.com\\\/wp-content\\\/uploads\\\/asOf-asAtpng.png?strip=all\",\"width\":779,\"height\":535},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\\\/\\\/developer.benify.com\\\/queries\\\/#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\\\/\\\/developer.benify.com\\\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Queries\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\\\/\\\/developer.benify.com\\\/#website\",\"url\":\"https:\\\/\\\/developer.benify.com\\\/\",\"name\":\"Benifex Developer Portal\",\"description\":\"A strong API capability that allows easy connection\",\"publisher\":{\"@id\":\"https:\\\/\\\/developer.benify.com\\\/#organization\"},\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\\\/\\\/developer.benify.com\\\/?s={search_term_string}\"},\"query-input\":{\"@type\":\"PropertyValueSpecification\",\"valueRequired\":true,\"valueName\":\"search_term_string\"}}],\"inLanguage\":\"en-US\"},{\"@type\":\"Organization\",\"@id\":\"https:\\\/\\\/developer.benify.com\\\/#organization\",\"name\":\"Benifex Developer Portal\",\"url\":\"https:\\\/\\\/developer.benify.com\\\/\",\"logo\":{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\\\/\\\/developer.benify.com\\\/#\\\/schema\\\/logo\\\/image\\\/\",\"url\":\"https:\\\/\\\/epa3f9ne4af.exactdn.com\\\/wp-content\\\/uploads\\\/Benifex-icon-rgb.png?strip=all\",\"contentUrl\":\"https:\\\/\\\/epa3f9ne4af.exactdn.com\\\/wp-content\\\/uploads\\\/Benifex-icon-rgb.png?strip=all\",\"width\":88,\"height\":118,\"caption\":\"Benifex Developer Portal\"},\"image\":{\"@id\":\"https:\\\/\\\/developer.benify.com\\\/#\\\/schema\\\/logo\\\/image\\\/\"}}]}<\/script>\n<!-- \/ Yoast SEO Premium plugin. -->","yoast_head_json":{"title":"Queries - Benify Developer Portal","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/developer.benify.com\/queries\/","og_locale":"en_US","og_type":"article","og_title":"Queries","og_description":"Queries The query part of the URI is for refining and\/or modifying what is to be read or modified. The query consists of keys and\/or key-value pairs. Each key is either one of the defined attributes of the API or an attribute described below. An API MUST return error code 400, Bad Request if one [&hellip;]","og_url":"https:\/\/developer.benify.com\/queries\/","og_site_name":"Benify Developer Portal","article_modified_time":"2024-09-06T07:38:20+00:00","og_image":[{"url":"https:\/\/developer.benify.com\/wp-content\/uploads\/asOf-asAtpng.png","type":"","width":"","height":""}],"twitter_card":"summary_large_image","twitter_misc":{"Est. reading time":"12 minutes"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"WebPage","@id":"https:\/\/developer.benify.com\/queries\/","url":"https:\/\/developer.benify.com\/queries\/","name":"Queries - Benify Developer Portal","isPartOf":{"@id":"https:\/\/developer.benify.com\/#website"},"primaryImageOfPage":{"@id":"https:\/\/developer.benify.com\/queries\/#primaryimage"},"image":{"@id":"https:\/\/developer.benify.com\/queries\/#primaryimage"},"thumbnailUrl":"https:\/\/developer.benify.com\/wp-content\/uploads\/asOf-asAtpng.png","datePublished":"2024-06-27T13:10:38+00:00","dateModified":"2024-09-06T07:38:20+00:00","breadcrumb":{"@id":"https:\/\/developer.benify.com\/queries\/#breadcrumb"},"inLanguage":"en-US","potentialAction":[{"@type":"ReadAction","target":["https:\/\/developer.benify.com\/queries\/"]}]},{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/developer.benify.com\/queries\/#primaryimage","url":"https:\/\/epa3f9ne4af.exactdn.com\/wp-content\/uploads\/asOf-asAtpng.png?strip=all","contentUrl":"https:\/\/epa3f9ne4af.exactdn.com\/wp-content\/uploads\/asOf-asAtpng.png?strip=all","width":779,"height":535},{"@type":"BreadcrumbList","@id":"https:\/\/developer.benify.com\/queries\/#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/developer.benify.com\/"},{"@type":"ListItem","position":2,"name":"Queries"}]},{"@type":"WebSite","@id":"https:\/\/developer.benify.com\/#website","url":"https:\/\/developer.benify.com\/","name":"Benifex Developer Portal","description":"A strong API capability that allows easy connection","publisher":{"@id":"https:\/\/developer.benify.com\/#organization"},"potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/developer.benify.com\/?s={search_term_string}"},"query-input":{"@type":"PropertyValueSpecification","valueRequired":true,"valueName":"search_term_string"}}],"inLanguage":"en-US"},{"@type":"Organization","@id":"https:\/\/developer.benify.com\/#organization","name":"Benifex Developer Portal","url":"https:\/\/developer.benify.com\/","logo":{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/developer.benify.com\/#\/schema\/logo\/image\/","url":"https:\/\/epa3f9ne4af.exactdn.com\/wp-content\/uploads\/Benifex-icon-rgb.png?strip=all","contentUrl":"https:\/\/epa3f9ne4af.exactdn.com\/wp-content\/uploads\/Benifex-icon-rgb.png?strip=all","width":88,"height":118,"caption":"Benifex Developer Portal"},"image":{"@id":"https:\/\/developer.benify.com\/#\/schema\/logo\/image\/"}}]}},"_links":{"self":[{"href":"https:\/\/developer.benify.com\/wp-json\/wp\/v2\/pages\/566","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/developer.benify.com\/wp-json\/wp\/v2\/pages"}],"about":[{"href":"https:\/\/developer.benify.com\/wp-json\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"https:\/\/developer.benify.com\/wp-json\/wp\/v2\/users\/3"}],"replies":[{"embeddable":true,"href":"https:\/\/developer.benify.com\/wp-json\/wp\/v2\/comments?post=566"}],"version-history":[{"count":5,"href":"https:\/\/developer.benify.com\/wp-json\/wp\/v2\/pages\/566\/revisions"}],"predecessor-version":[{"id":689,"href":"https:\/\/developer.benify.com\/wp-json\/wp\/v2\/pages\/566\/revisions\/689"}],"wp:attachment":[{"href":"https:\/\/developer.benify.com\/wp-json\/wp\/v2\/media?parent=566"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}