adapt-authoring-api 2.2.0 → 3.1.0

package/docs/writing-an-api.md

@@ -53,6 +53,8 @@ class NotesModule extends AbstractApiModule {
 export default NotesModule
 ```
 
+> **Tip:** For new modules, consider defining routes in a `routes.json` file instead of calling `useDefaultRouteConfig()`. See [Custom routes](#custom-routes) for details.
+
 With a schema at `schema/note.schema.json`:
 
 ```json

package/lib/AbstractApiModule.js

@@ -12,11 +12,11 @@ class AbstractApiModule extends AbstractModule {
   get DEFAULT_ROUTES () {
     const readPerms = [`read:${this.permissionsScope || this.root}`]
     const writePerms = [`write:${this.permissionsScope || this.root}`]
-    const handler = this.requestHandler()
+    const handler = this.requestHandler.bind(this)
     return [
       {
         route: '/',
-        handlers: { post: handler, get: this.queryHandler() },
+        handlers: { post: handler, get: this.queryHandler.bind(this) },
         permissions: { post: writePerms, get: readPerms }
       },
       {
@@ -33,7 +33,7 @@ class AbstractApiModule extends AbstractModule {
         route: '/query',
         validate: false,
         modifying: false,
-        handlers: { post: this.queryHandler() },
+        handlers: { post: this.queryHandler.bind(this) },
         permissions: { post: readPerms }
       }
     ]
@@ -153,11 +153,6 @@ class AbstractApiModule extends AbstractModule {
 
     const config = await loadRouteConfig(this.rootDir, this, {
       schema: 'apiroutes',
-      handlerAliases: {
-        default: this.requestHandler(),
-        query: this.queryHandler(),
-        serveSchema: this.serveSchema.bind(this)
-      },
       defaults: new URL('./default-routes.json', import.meta.url).pathname
     })
     if (config) this.applyRouteConfig(config)
@@ -241,26 +236,43 @@ class AbstractApiModule extends AbstractModule {
 
   /**
    * Applies route configuration loaded from routes.json.
-   * Expands `${scope}` permission placeholders with `this.permissionsScope || this.root`.
+   * Resolves `${scope}`, `${schemaName}`, and `${collectionName}` placeholders
+   * throughout the route config (permissions, meta, etc.).
    * @param {Object} config The route config object returned by loadRouteConfig
    */
   applyRouteConfig (config) {
     /** @ignore */ this.root = config.root
     if (config.schemaName !== undefined) this.schemaName = config.schemaName
     if (config.collectionName !== undefined) this.collectionName = config.collectionName
-    const scope = this.permissionsScope || this.root
-    this.routes = config.routes.map(r => {
-      if (!r.permissions) return r
-      return {
-        ...r,
-        permissions: Object.fromEntries(
-          Object.entries(r.permissions).map(([method, perms]) => [
-            method,
-            Array.isArray(perms) ? perms.map(p => p.replace('${scope}', scope)) : perms // eslint-disable-line no-template-curly-in-string
-          ])
-        )
-      }
-    })
+    if (config.permissionsScope !== undefined) this.permissionsScope = config.permissionsScope
+    /* eslint-disable no-template-curly-in-string */
+    const replacements = {
+      '${scope}': this.permissionsScope || this.root,
+      '${schemaName}': this.schemaName,
+      '${collectionName}': this.collectionName
+    }
+    /* eslint-enable no-template-curly-in-string */
+    this.routes = config.routes.map(r => this.replacePlaceholders(r, replacements))
+  }
+
+  /**
+   * Recursively replaces placeholder strings in an object tree.
+   * Non-string values (functions, numbers, booleans, null) pass through unchanged.
+   * @param {*} obj The value to process
+   * @param {Object<string,string>} replacements Map of placeholder to replacement value
+   * @returns {*} The value with all placeholders resolved
+   */
+  replacePlaceholders (obj, replacements) {
+    if (typeof obj === 'string') {
+      return Object.entries(replacements).reduce((s, [k, v]) => v != null ? s.replaceAll(k, v) : s, obj)
+    }
+    if (Array.isArray(obj)) return obj.map(item => this.replacePlaceholders(item, replacements))
+    if (obj && typeof obj === 'object' && obj.constructor === Object) {
+      return Object.fromEntries(
+        Object.entries(obj).map(([k, v]) => [k, this.replacePlaceholders(v, replacements)])
+      )
+    }
+    return obj
   }
 
   /**
@@ -390,135 +402,129 @@ class AbstractApiModule extends AbstractModule {
    * Middleware to handle a generic API request. Supports POST, GET, PUT and DELETE of items in the database.
    * @return {Function} Express middleware function
    */
-  requestHandler () {
-    const requestHandler = async (req, res, next) => {
-      const method = req.method.toLowerCase()
-      const func = this[httpMethodToDBFunction(method)]
-      if (!func) {
-        return next(this.app.errors.HTTP_METHOD_NOT_SUPPORTED.setData({ method }))
-      }
-      let data
-      try {
-        await this.requestHook.invoke(req)
-        const preCheck = method !== 'get' && method !== 'post'
-        const postCheck = method === 'get'
-        if (preCheck) {
-          await this.checkAccess(req, req.apiData.query)
-        }
-        data = await func.apply(this, argsFromReq(req))
-        if (postCheck) {
-          data = await this.checkAccess(req, data)
-        }
-        data = await this.sanitise(req.apiData.schemaName, data, { isInternal: true, strict: false })
-      } catch (e) {
-        return next(e)
+  async requestHandler (req, res, next) {
+    const method = req.method.toLowerCase()
+    const func = this[httpMethodToDBFunction(method)]
+    if (!func) {
+      return next(this.app.errors.HTTP_METHOD_NOT_SUPPORTED.setData({ method }))
+    }
+    let data
+    try {
+      await this.requestHook.invoke(req)
+      const preCheck = method !== 'get' && method !== 'post'
+      const postCheck = method === 'get'
+      if (preCheck) {
+        await this.checkAccess(req, req.apiData.query)
       }
-      if (Array.isArray(data) && req.params._id) { // special case for when _id param is present
-        if (!data.length) {
-          return next(this.app.errors.NOT_FOUND.setData({ id: req.params.id, type: req.apiData.schemaName }))
-        }
-        data = data[0]
+      data = await func.apply(this, argsFromReq(req))
+      if (postCheck) {
+        data = await this.checkAccess(req, data)
       }
-      if (method !== 'get') {
-        const resource = Array.isArray(data) ? req.apiData.query : data._id.toString()
-        this.log('debug', `API_${func.name.toUpperCase()}`, resource, 'by', req.auth.user._id.toString())
+      data = await this.sanitise(req.apiData.schemaName, data, { isInternal: true, strict: false })
+    } catch (e) {
+      return next(e)
+    }
+    if (Array.isArray(data) && req.params._id) { // special case for when _id param is present
+      if (!data.length) {
+        return next(this.app.errors.NOT_FOUND.setData({ id: req.params.id, type: req.apiData.schemaName }))
       }
-      res.status(this.mapStatusCode(method)).json(data)
+      data = data[0]
     }
-    return requestHandler
+    if (method !== 'get') {
+      const resource = Array.isArray(data) ? req.apiData.query : data._id.toString()
+      this.log('debug', `API_${func.name.toUpperCase()}`, resource, 'by', req.auth.user._id.toString())
+    }
+    res.status(this.mapStatusCode(method)).json(data)
   }
 
   /**
    * Express request handler for advanced API queries. Supports collation/limit/page/skip/sort and pagination. For incoming query data to be correctly parsed, it must be sent as body data using a POST request.
    * @return {function}
    */
-  queryHandler () {
-    const queryHandler = async (req, res, next) => {
-      try {
-        const opts = {
-          schemaName: req.apiData.schemaName,
-          collectionName: req.apiData.collectionName
-        }
-        const mongoOpts = {}
-        // find and remove mongo options from the query
-        Object.entries(req.apiData.query).forEach(([key, val]) => {
-          if (['collation', 'limit', 'page', 'skip', 'sort'].includes(key)) {
-            try {
-              mongoOpts[key] = JSON.parse(req.apiData.query[key])
-            } catch (e) {
-              this.log('warn', `failed to parse query ${key} param '${mongoOpts[key]}', ${e}`)
-            }
-            delete req.apiData.query[key]
-          } else {
-            // otherwise assume we have a query field or option and store for later processing
-            opts[key] = val
-          }
-        })
-        // handle search parameter
-        const search = req.apiData.query.search
-        if (search) {
-          delete req.apiData.query.search
+  async queryHandler (req, res, next) {
+    try {
+      const opts = {
+        schemaName: req.apiData.schemaName,
+        collectionName: req.apiData.collectionName
+      }
+      const mongoOpts = {}
+      // find and remove mongo options from the query
+      Object.entries(req.apiData.query).forEach(([key, val]) => {
+        if (['collation', 'limit', 'page', 'skip', 'sort'].includes(key)) {
           try {
-            const schema = await this.getSchema(req.apiData.schemaName)
-            if (schema && schema.built && schema.built.properties) {
-              const searchableFields = Object.keys(schema.built.properties).filter(
-                field => schema.built.properties[field].isSearchable === true
-              )
-              if (searchableFields.length) {
-                // escape special regex characters to prevent ReDoS attacks
-                const escapedSearch = search.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-                const regex = { $regex: escapedSearch, $options: 'i' }
-                const searchConditions = searchableFields.map(f => ({ [f]: regex }))
-                // merge with existing $or if present
-                if (req.apiData.query.$or) {
-                  req.apiData.query.$and = [
-                    { $or: req.apiData.query.$or },
-                    { $or: searchConditions }
-                  ]
-                  delete req.apiData.query.$or
-                } else {
-                  req.apiData.query.$or = searchConditions
-                }
+            mongoOpts[key] = JSON.parse(req.apiData.query[key])
+          } catch (e) {
+            this.log('warn', `failed to parse query ${key} param '${mongoOpts[key]}', ${e}`)
+          }
+          delete req.apiData.query[key]
+        } else {
+          // otherwise assume we have a query field or option and store for later processing
+          opts[key] = val
+        }
+      })
+      // handle search parameter
+      const search = req.apiData.query.search
+      if (search) {
+        delete req.apiData.query.search
+        try {
+          const schema = await this.getSchema(req.apiData.schemaName)
+          if (schema && schema.built && schema.built.properties) {
+            const searchableFields = Object.keys(schema.built.properties).filter(
+              field => schema.built.properties[field].isSearchable === true
+            )
+            if (searchableFields.length) {
+              // escape special regex characters to prevent ReDoS attacks
+              const escapedSearch = search.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+              const regex = { $regex: escapedSearch, $options: 'i' }
+              const searchConditions = searchableFields.map(f => ({ [f]: regex }))
+              // merge with existing $or if present
+              if (req.apiData.query.$or) {
+                req.apiData.query.$and = [
+                  { $or: req.apiData.query.$or },
+                  { $or: searchConditions }
+                ]
+                delete req.apiData.query.$or
+              } else {
+                req.apiData.query.$or = searchConditions
               }
             }
-          } catch (e) {
-            this.log('warn', `failed to process search parameter, ${e.message}`)
           }
+        } catch (e) {
+          this.log('warn', `failed to process search parameter, ${e.message}`)
         }
-        req.apiData.query = await this.parseQuery(req.apiData.schemaName, req.body, mongoOpts)
-        // remove any valid query keys from the options
-        Object.keys(req.apiData.query).forEach(key => delete opts[key])
+      }
+      req.apiData.query = await this.parseQuery(req.apiData.schemaName, req.body, mongoOpts)
+      // remove any valid query keys from the options
+      Object.keys(req.apiData.query).forEach(key => delete opts[key])
 
-        await this.requestHook.invoke(req)
+      await this.requestHook.invoke(req)
 
-        await this.setUpPagination(req, res, mongoOpts)
+      await this.setUpPagination(req, res, mongoOpts)
 
-        let results = await this.find(req.apiData.query, opts, mongoOpts)
+      let results = await this.find(req.apiData.query, opts, mongoOpts)
 
-        results = await this.checkAccess(req, results)
+      results = await this.checkAccess(req, results)
 
-        // If checkAccess filtered some results, fetch more to fill the page
-        const pageSize = mongoOpts.limit
-        if (pageSize && results.length < pageSize) {
-          let fetchSkip = mongoOpts.skip + pageSize
-          while (results.length < pageSize) {
-            const extra = await this.find(req.apiData.query, opts, { ...mongoOpts, skip: fetchSkip })
-            if (!extra.length) break
-            const filtered = await this.checkAccess(req, extra)
-            results = results.concat(filtered)
-            fetchSkip += extra.length
-          }
-          if (results.length > pageSize) results = results.slice(0, pageSize)
+      // If checkAccess filtered some results, fetch more to fill the page
+      const pageSize = mongoOpts.limit
+      if (pageSize && results.length < pageSize) {
+        let fetchSkip = mongoOpts.skip + pageSize
+        while (results.length < pageSize) {
+          const extra = await this.find(req.apiData.query, opts, { ...mongoOpts, skip: fetchSkip })
+          if (!extra.length) break
+          const filtered = await this.checkAccess(req, extra)
+          results = results.concat(filtered)
+          fetchSkip += extra.length
         }
+        if (results.length > pageSize) results = results.slice(0, pageSize)
+      }
 
-        results = await this.sanitise(req.apiData.schemaName, results, { isInternal: true, strict: false })
+      results = await this.sanitise(req.apiData.schemaName, results, { isInternal: true, strict: false })
 
-        res.status(this.mapStatusCode('get')).json(results)
-      } catch (e) {
-        return next(e)
-      }
+      res.status(this.mapStatusCode('get')).json(results)
+    } catch (e) {
+      return next(e)
     }
-    return queryHandler
   }
 
   /**

package/lib/default-routes.json

@@ -2,25 +2,147 @@
   "routes": [
     {
       "route": "/",
-      "handlers": { "post": "default", "get": "default" },
-      "permissions": { "post": ["write:${scope}"], "get": ["read:${scope}"] }
+      "handlers": { "post": "requestHandler", "get": "queryHandler" },
+      "permissions": { "post": ["write:${scope}"], "get": ["read:${scope}"] },
+      "meta": {
+        "post": {
+          "summary": "Insert a new ${schemaName} document",
+          "requestBody": {
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/${schemaName}" }
+              }
+            }
+          },
+          "responses": {
+            "201": {
+              "description": "The created ${schemaName} document",
+              "content": {
+                "application/json": {
+                  "schema": { "$ref": "#/components/schemas/${schemaName}" }
+                }
+              }
+            }
+          }
+        },
+        "get": {
+          "summary": "Retrieve all ${collectionName} documents",
+          "parameters": [
+            { "name": "limit", "in": "query", "description": "How many results to return" },
+            { "name": "page", "in": "query", "description": "The page of results to return" }
+          ],
+          "responses": {
+            "200": {
+              "description": "List of ${schemaName} documents",
+              "content": {
+                "application/json": {
+                  "schema": { "type": "array", "items": { "$ref": "#/components/schemas/${schemaName}" } }
+                }
+              }
+            }
+          }
+        }
+      }
     },
     {
       "route": "/schema",
       "handlers": { "get": "serveSchema" },
-      "permissions": { "get": ["read:schema"] }
+      "permissions": { "get": ["read:schema"] },
+      "meta": {
+        "get": { "summary": "Retrieve ${schemaName} schema" }
+      }
     },
     {
       "route": "/:_id",
-      "handlers": { "put": "default", "get": "default", "patch": "default", "delete": "default" },
-      "permissions": { "put": ["write:${scope}"], "get": ["read:${scope}"], "patch": ["write:${scope}"], "delete": ["write:${scope}"] }
+      "handlers": { "put": "requestHandler", "get": "requestHandler", "patch": "requestHandler", "delete": "requestHandler" },
+      "permissions": { "put": ["write:${scope}"], "get": ["read:${scope}"], "patch": ["write:${scope}"], "delete": ["write:${scope}"] },
+      "meta": {
+        "put": {
+          "summary": "Replace an existing ${schemaName} document",
+          "requestBody": {
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/${schemaName}" }
+              }
+            }
+          },
+          "responses": {
+            "200": {
+              "description": "The updated ${schemaName} document",
+              "content": {
+                "application/json": {
+                  "schema": { "$ref": "#/components/schemas/${schemaName}" }
+                }
+              }
+            }
+          }
+        },
+        "get": {
+          "summary": "Retrieve an existing ${schemaName} document",
+          "responses": {
+            "200": {
+              "description": "The ${schemaName} document",
+              "content": {
+                "application/json": {
+                  "schema": { "$ref": "#/components/schemas/${schemaName}" }
+                }
+              }
+            }
+          }
+        },
+        "patch": {
+          "summary": "Update an existing ${schemaName} document",
+          "requestBody": {
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/${schemaName}" }
+              }
+            }
+          },
+          "responses": {
+            "200": {
+              "description": "The updated ${schemaName} document",
+              "content": {
+                "application/json": {
+                  "schema": { "$ref": "#/components/schemas/${schemaName}" }
+                }
+              }
+            }
+          }
+        },
+        "delete": {
+          "summary": "Delete an existing ${schemaName} document",
+          "responses": {
+            "204": { "description": "Document deleted successfully" }
+          }
+        }
+      }
     },
     {
       "route": "/query",
       "validate": false,
       "modifying": false,
-      "handlers": { "post": "query" },
-      "permissions": { "post": ["read:${scope}"] }
+      "handlers": { "post": "queryHandler" },
+      "permissions": { "post": ["read:${scope}"] },
+      "meta": {
+        "post": {
+          "summary": "Query all ${collectionName}",
+          "parameters": [
+            { "name": "limit", "in": "query", "description": "How many results to return" },
+            { "name": "page", "in": "query", "description": "The page of results to return" }
+          ],
+          "responses": {
+            "200": {
+              "description": "List of ${schemaName} documents",
+              "content": {
+                "application/json": {
+                  "schema": { "type": "array", "items": { "$ref": "#/components/schemas/${schemaName}" } }
+                }
+              }
+            }
+          }
+        }
+      }
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adapt-authoring-api",
-  "version": "2.2.0",
+  "version": "3.1.0",
   "description": "Abstract module for creating APIs",
   "homepage": "https://github.com/adapt-security/adapt-authoring-api",
   "license": "GPL-3.0",

package/tests/AbstractApiModule.spec.js

@@ -9,8 +9,8 @@ function createInstance (overrides = {}) {
   instance.schemaName = undefined
   instance.collectionName = undefined
   instance.routes = []
-  instance.requestHandler = () => function defaultRequestHandler () {}
-  instance.queryHandler = () => function queryHandler () {}
+  instance.requestHandler = function defaultRequestHandler () {}
+  instance.queryHandler = function queryHandler () {}
   instance.serveSchema = function serveSchema () {}
   Object.assign(instance, overrides)
   return instance