Merge pull request #1168 from RobAndrewHurst/xyz-key-query-docs

User Key and Query docs

mod/query.js

@@ -1,4 +1,54 @@
 /**
+## query🔎
+The Query API allows for parameterised queries from cached templates to be sent to a database connection defined in the process environment.
+
+`%{id}` parameter prefixed with \% will be provided as an array with the query.
+
+`${table}` parameter prefixed with \$ will substituted in the template before the query is sent to the DBS connection. Parameter values wich are substituted may only contain a set of whitelisted characters `!/^[A-Za-z0-9,"'._-]*$/.test()`.
+
+Roles will be checked against the user if a `layer` parameter is provided.
+
+The `${filter}` parameter will be substituted with a SQL filter generated by the [sqlFilter](https://github.com/GEOLYTIX/xyz/blob/main/mod/utils/sqlFilter.js) module.
+
+In order to make a request to the query endpoint you will need to provide an api key in the query params of the request.
+
+### Example of a query with an api key as a param
+
+```
+/api/query?locale=locale_name&layer=layer_name&template=template_name&key=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
+```
+Endpoint : /api/query
+
+### params :
+- locale: `LOCALE_KEY` - Required
+- layer: `LAYER_KEY` - Required
+- template: `TEMPLATE_KEY` - required
+- key: `API_KEY` - required if making a request as a 3rd party api call
+- dbs: `DBS_KEY` - required if not set in workspace
+
+The response of a query will typically result in a text/json response.
+
+### Example Response
+```json
+[
+    {
+        "Postal Sector": "Grand Total",
+        "Total HHs": null,
+        "Deliverable HHs": null,
+        "% Deliverable HHs": null,
+        "Target HHs": null
+    },
+    {
+        "Postal Sector": null,
+        "Total HHs": null,
+        "Deliverable HHs": null,
+        "% Deliverable HHs": null,
+        "Target HHs": "0"
+    }
+]
+```
+
+> All status codes are defined by [RFC 9110](https://httpwg.org/specs/rfc9110.html#overview.of.status.codes)
 @module query
 */
 

mod/user/key.js

@@ -1,4 +1,20 @@
 /**
+## User Key 🔑
+The endpoint `/api/user/key` allows a user with the the api-key privileges to create an api key.
+Each time this end point is run it will replace the key in the ACL.
+
+> URL /api/user/key
+
+### Example URL : 
+```
+https://yourdomain.com/api/user/key
+```
+
+### Example Response:
+
+```
+eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
+```
 @module /user/key
 */