adapt-authoring-api 1.3.1 → 1.3.2

package/.github/workflows/new.yml

@@ -1,19 +1,15 @@
-name: Add to main project
+# Calls the org-level reusable workflow to add PRs to the TODO Board
+
+name: Add PR to Project
 
 on:
-  issues:
-    types:
-      - opened
   pull_request:
     types:
       - opened
+      - reopened
 
 jobs:
   add-to-project:
-    name: Add to main project
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/add-to-project@v0.1.0
-        with:
-          project-url: https://github.com/orgs/adapt-security/projects/5
-          github-token: ${{ secrets.PROJECTS_SECRET }}
+    uses: adapt-security/.github/.github/workflows/new.yml@main
+    secrets:
+      PROJECTS_SECRET: ${{ secrets.PROJECTS_SECRET }}

package/adapt-authoring.json

@@ -3,7 +3,7 @@
   "documentation": {
     "enable": true,
     "manualPages": {
-      "writing-an-api.md": "basics"
+      "writing-an-api.md": "development"
     }
   }
 }

package/docs/request-response.md

@@ -0,0 +1,186 @@
+# Custom request and response data
+
+This guide documents the custom properties added to the standard Express.js [Request (req)](https://expressjs.com/en/api.html#req.properties) and [Response (res)](https://expressjs.com/en/api.html#res.properties) objects by various Adapt authoring tool modules.
+
+See the [Express.js documentation](https://expressjs.com/en/api.html) for the standard properties.
+
+## Summary
+
+| Property | Added by | Purpose |
+| -------- | -------- | ------- |
+| `req.auth` | adapt-authoring-auth | Authentication data (user, token, scopes) |
+| `req.apiData` | adapt-authoring-api | Pre-processed API request data |
+| `req.translate` | adapt-authoring-lang | Translation function |
+| `req.routeConfig` | adapt-authoring-server | Route configuration |
+| `req.hasBody` | adapt-authoring-server | Whether request has body data |
+| `req.hasParams` | adapt-authoring-server | Whether request has route params |
+| `req.hasQuery` | adapt-authoring-server | Whether request has query string |
+| `res.sendError` | adapt-authoring-server | Send formatted error responses |
+
+## Request object (req)
+
+### req.auth
+
+Added by: `adapt-authoring-auth`
+
+Contains authentication data for the current request. This object is always present but may not contain all the expected data (e.g. in the case of unauthenticated requests).
+
+```javascript
+{
+  header: {
+    type: 'Bearer',           // Auth header type
+    value: 'eyJhbGci...'      // The raw token string
+  },
+  user: {                     // The authenticated user document
+    _id: ObjectId('507f1f77bcf86cd799439011'),
+    email: 'user@example.com',
+    firstName: 'John',
+    lastName: 'Doe',
+    roles: ['507f1f77bcf86cd799439012']
+  },
+  token: {                    // The decoded JWT payload
+    type: 'local',
+    userId: '507f1f77bcf86cd799439011',
+    signature: 'abc123',
+    iat: 1609459200,
+    exp: 1609545600
+  },
+  scopes: [                   // Array of permission scopes
+    'read:content',
+    'write:content'
+  ],
+  isSuper: false,             // Whether user has super privileges (*:*)
+  userSchemaName: 'localauthuser'  // Schema used for the user
+}
+```
+
+### req.apiData _(AbstractApiModule subclasses only)_
+
+Added by: `adapt-authoring-api` (AbstractApiModule)
+
+Contains pre-processed API request data. This is set by the `processRequestMiddleware` method for routes using `AbstractApiModule`.
+
+```javascript
+{
+  collectionName: 'content',   // MongoDB collection name
+  schemaName: 'course',        // JSON schema name for validation
+  config: { ... },             // Route configuration
+  data: { ... },               // Request body data (for POST/PUT/PATCH)
+  query: { ... },              // Combined params and query string
+  modifying: true              // Whether request modifies data (POST/PUT/PATCH/DELETE)
+  validate: false,             // Whether data will be validated
+}
+```
+
+### req.translate
+
+Added by: `adapt-authoring-lang` (LangModule.addTranslationUtils)
+
+A function for translating strings based on the client's accepted language.
+
+**Signature:**
+
+```javascript
+req.translate(key: string, data?: object): string
+```
+
+**Example usage:**
+
+```javascript
+async myHandler (req, res, next) {
+  // Simple translation
+  const title = req.translate('app.newpagetitle')
+  
+  // Translation with interpolation
+  const message = req.translate('app.welcomemessage', { name: 'John' })
+  
+  // Translate a response message
+  res.json({ message: req.translate('app.success') })
+}
+```
+
+### req.routeConfig
+
+Added by: `adapt-authoring-server` (ServerUtils.cacheRouteConfig)
+
+Contains the configuration object for the current route.
+
+```javascript
+{
+  route: '/query',
+  internal: false,       // Whether route is internal-only
+  handlers: { ... },
+  permissions: { ... }
+}
+```
+
+### req.hasBody, req.hasParams, req.hasQuery
+
+Added by: `adapt-authoring-server` (ServerUtils.addExistenceProps)
+
+Boolean properties indicating whether the request has non-empty body, params, or query data. Useful for quickly checking if data was provided.
+
+> **Note:** Body data is ignored for GET requests — `req.hasBody` will always be `false` for GET.
+
+**Example usage:**
+
+```javascript
+async myHandler (req, res, next) {
+  if (!req.hasParams) {
+    return res.sendError(this.app.errors.MISSING_PARAMS)
+  }
+  
+  if (!req.hasBody) {
+    return res.sendError(this.app.errors.MISSING_BODY)
+  }
+  
+  if (req.hasQuery) {
+    // Apply query filters
+  }
+}
+```
+
+## Response object (res)
+
+### res.sendError
+
+Added by: `adapt-authoring-server` (ServerUtils.addErrorHandler)
+
+A convenience method for sending error responses. Automatically formats errors, sets the appropriate status code, and translates the error message if `req.translate` is available.
+
+**Signature:**
+
+```javascript
+res.sendError(error: AdaptError | Error): void
+```
+
+**Example usage:**
+
+```javascript
+async myHandler (req, res, next) {
+  try {
+    const result = await this.doSomething()
+    res.json(result)
+  } catch (e) {
+    // Send a predefined error
+    res.sendError(this.app.errors.NOT_FOUND)
+    
+    // Or send with custom data
+    res.sendError(this.app.errors.VALIDATION_FAILED.setData({ 
+      field: 'email' 
+    }))
+    
+    // Or pass through an unexpected error (becomes SERVER_ERROR)
+    res.sendError(e)
+  }
+}
+```
+
+The error response format:
+
+```json
+{
+  "code": "NOT_FOUND",
+  "message": "Resource not found"
+}
+```

package/docs/writing-an-api.md

@@ -1,135 +1,492 @@
-# Writing an API
+# Writing an API module
 
-_**Note:** before using this functionality, it is worth having an understanding of how to write basic custom modules first. See [this page](`adapt-authoring-api` module) for more._
+This guide explains how to create a REST API module by extending `AbstractApiModule`. This is the recommended approach for any module that needs to expose HTTP endpoints for CRUD operations on database collections. 
 
-The `adapt-authoring-api` module makes defining custom APIs simple by providing abstract classes and utilities you can use in your own modules to replace the common boilerplate code required when writing an API.
+By extending `AbstractApiModule`, your module automatically gets:
 
-By extending the [AbstractAPIModule](../class/adapt_authoring_restructure/adapt-authoring-api/lib/module.js~AbstractApiModule.html) class, you get the following as standard:
-- Boiler-plate code for defining router and endpoints
-- Default handlers for incoming HTTP requests (with support for querying)
-- Support for custom middleware
-- Auto-loading of database schemas
-- Automated (and overridable) database interaction
-- Default permissions
+- REST endpoints for CRUD operations (POST, GET, PUT, PATCH, DELETE)
+- Request validation against JSON schemas
+- Database interaction via the MongoDB module
+- Permission-based route security
+- Pagination support for list queries
+- Data caching
+- Hooks for customising behaviour at key points
 
-## Defining your API
 
-To define an API, all you need to do is override the `setValues` function, making sure to change the values as appropriate.
+## Quick navigation
 
-See the below table for all values:
+- [Prerequisites](#prerequisites)
+- [Quick start](#quick-start)
+- [Module configuration](#module-configuration)
+- [Custom routes](#custom-routes)
+- [Requests](#requests)
+- [Database operations](#database-operations)
+- [Hooks](#hooks)
+- [Overriding methods](#overriding-methods)
+- [Permissions](#permissions)
+- [Caching](#caching)
+- [Error handling](#error-handling)
+- [Writing documentation](#writing-documentation)
 
-| Attribute | Type | Description | Optional |
-| --------- | ---- | ----------- | -------- |
-| `root` | `String` | This value will be used as the route for any URLs (e.g. `/api/mymodule`). For APIs which deal with collections of data, the general rule is to use the plural form (ie. `/api/items`). | `false` |
-| `router` | `Router` | The Router instance used for HTTP requests. If not defined, a new router will be created using the `root` value. | `true` |
-| `routes` | `Array<ApiRoute>` | Definitions for any routes to be added to the API router. | `false` |
-| `collectionName` | `String` | Default DB collection to store data to (can be overridden by individual handlers). | `false` |
+## Prerequisites
 
-### Defining routes
+Before creating an API module, you should understand:
+- [How to write a basic module](../adapt-authoring-core/writing-a-module.md)
+- [How schemas work](../adapt-authoring-jsonschema/defining-schemas.md)
 
-Before your API can handle HTTP requests, you must define which routes the router should respond to. If your module extends AbstractApiModule, this is simply a case of setting the [`routes`](../class/node_modules/adapt-authoring-api/lib/abstractApiModule.js~AbstractApiModule.html#instance-member-routes) instance variable:
+## Quick start
 
-```js
-this.routes = [
-  // route config here
-]
+Here's a minimal API module:
+
+```javascript
+import AbstractApiModule from 'adapt-authoring-api'
+
+class NotesModule extends AbstractApiModule {
+  async setValues () {
+    this.root = 'notes'
+    this.collectionName = 'notes'
+    this.schemaName = 'note'
+    this.useDefaultRouteConfig()
+  }
+}
+
+export default NotesModule
+```
+
+With a schema at `schema/note.schema.json`:
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$anchor": "note",
+  "type": "object",
+  "properties": {
+    "title": {
+      "type": "string",
+      "description": "Note title"
+    },
+    "content": {
+      "type": "string",
+      "description": "Note content"
+    }
+  },
+  "required": ["title"]
+}
+```
+
+This creates the following endpoints:
+
+| Method | Route | Description |
+| ------ | ----- | ----------- |
+| POST | `/api/notes` | Create a note |
+| GET | `/api/notes` | List all notes |
+| GET | `/api/notes/:_id` | Get a single note |
+| PUT | `/api/notes/:_id` | Replace a note |
+| PATCH | `/api/notes/:_id` | Update a note |
+| DELETE | `/api/notes/:_id` | Delete a note |
+| GET | `/api/notes/schema` | Get the JSON schema |
+| POST | `/api/notes/query` | Advanced query with pagination |
+
+## Module configuration
+
+### Required values
+
+Override `setValues()` to configure your module:
+
+```javascript
+async setValues () {
+  this.root = 'notes'           // URL path: /api/notes
+  this.collectionName = 'notes' // MongoDB collection name
+  this.schemaName = 'note'      // Default schema for validation
+  this.useDefaultRouteConfig()  // Use standard CRUD routes
+}
 ```
 
-#### General tips
-The Adapt server module maps to Express functionality as closely as possible, and as such adopts the same middleware/handler concepts (with a few minor changes). It is therefore very useful to have some understanding of how the Express stack works, particularly with regards to the execution order of middleware and handlers. For more details on route handling, see the [official Express documentation](https://expressjs.com/en/guide/routing.html).
+| Property | Type | Required | Description |
+| -------- | ---- | -------- | ----------- |
+| `root` | String | Yes* | URL path for the API (e.g., `notes` → `/api/notes`) |
+| `router` | Router | Yes* | Router instance (created automatically if `root` is set) |
+| `routes` | Array | Yes | Route definitions |
+| `collectionName` | String | Yes | MongoDB collection name |
+| `schemaName` | String | No | Default schema name for validation |
+| `permissionsScope` | String | No | Override the scope used for permissions (defaults to `root`) |
 
-Here are a few useful notes/tips:
+*Either `root` or `router` must be set.
 
-- The `route` attribute of each route definition is very powerful, and handles params/queries/etc. in the same way as Express (see [the Express docs](https://expressjs.com/en/guide/routing.html) for more).
-- Use the API's middleware to perform any tasks which are common to all routes, such as checking and formatting the request data
-- You only need to specify route handlers for the routes/HTTP methods you want to enable, access will be blocked to any route/HTTP method combinations you haven't defined
-- You can run route-specific middleware by adding it as a handler to the route config (see example 2. below)
+### Using default routes
 
-#### Using the default route configuration
-Instead of defining each route yourself, the AbstractApiModule class also gives you a set of default routes which you can use if you wish:
-```js
+Call `useDefaultRouteConfig()` to use the standard CRUD routes:
+
+```javascript
+async setValues () {
+  this.root = 'notes'
+  this.collectionName = 'notes'
+  this.schemaName = 'note'
+  this.useDefaultRouteConfig()
+}
+```
+
+The default routes are:
+
+```javascript
 [
-  // POST, no params
   {
     route: '/',
-    modifying: true,
-    handlers: {
-      post: this.requestHandler()
-    }
+    handlers: { post: handler, get: queryHandler },
+    permissions: { post: ['write:notes'], get: ['read:notes'] }
   },
-  // GET, optional _id param
   {
-    route: '/:_id?',
-    handlers: {
-      get: this.requestHandler()
-    }
+    route: '/schema',
+    handlers: { get: serveSchema },
+    permissions: { get: ['read:schema'] }
   },
-  // PUT/DELETE, mandatory _id param
   {
     route: '/:_id',
-    modifying: true,
-    handlers: {
-      put: this.requestHandler(),
-      delete: this.requestHandler()
-    }
+    handlers: { put: handler, get: handler, patch: handler, delete: handler },
+    permissions: { put: ['write:notes'], get: ['read:notes'], patch: ['write:notes'], delete: ['write:notes'] }
   },
-  // POST custom query handler
   {
     route: '/query',
     validate: false,
-    handlers: {
-      post: this.queryHandler()
-    }
+    modifying: false,
+    handlers: { post: queryHandler },
+    permissions: { post: ['read:notes'] }
   }
-];
-```
-To use the above configuration, you simply need to call the `useDefaultRouteConfig` function:
-```js
-async setValues() {
-  this.useDefaultRouteConfig();
-}
-```
-
-### Example configurations
-```js
-/**
-* Basic configuration
-*/
-async setValues() {
-  const server = await this.app.waitForModule('server');
-  this.root = 'myapi';
-  this.collectionName = 'mycollection';
-  this.router = server.api.createChildRouter('myapi'); // optional
-  this.router.addMiddleware(this.myMiddleware);
+]
+```
+
+## Custom routes
+
+You can define custom routes by setting `this.routes` directly, or by adding to the default routes:
+
+### Adding routes to the defaults
+
+```javascript
+async setValues () {
+  this.root = 'notes'
+  this.collectionName = 'notes'
+  this.schemaName = 'note'
+  // initialise the defaults routes
+  this.useDefaultRouteConfig()
+  // Add custom route
+  this.routes.push({
+    route: '/archive/:_id',
+    handlers: { post: this.archiveHandler.bind(this) },
+    permissions: { post: ['write:notes'] }
+  })
+}
+```
+
+### Fully custom routes
+
+```javascript
+async setValues () {
+  this.root = 'notes'
+  this.collectionName = 'notes'
+  this.schemaName = 'note'
+  // here we define our own completely custom list of routes, with no call to this.useDefaultRouteConfig
   this.routes = [
     {
       route: '/',
-      handlers: { // if you need reference to 'this' in your handler, remember to bind
-        get: this.myRequestHandler.bind(this)
+      handlers: {
+        get: this.listHandler.bind(this),
+        post: this.createHandler.bind(this)
+      },
+      permissions: {
+        get: ['read:notes'],
+        post: ['write:notes']
       }
     },
     {
-      route: '/two',
-      handlers: { // example of route-level middleware
-        post: [ this.myOtherMiddleware, this.myPostHandler ]
+      route: '/:_id',
+      handlers: {
+        get: this.getHandler.bind(this),
+        delete: this.deleteHandler.bind(this)
+      },
+      permissions: {
+        get: ['read:notes'],
+        delete: ['write:notes']
       }
     }
-  ];
+  ]
 }
-/**
-* Custom route configuration
-*/
-async setValues() {
-  // @note other values omitted for brevity
-  this.routes = [
-    {
-      route: '/',
-      schemaName: 'myschema', // can specify custom schema/collection like this
-      collectionName: 'myothercollection',
-      handlers: {
-        get: this.myRequestHandler.bind(this)
-      }
+```
+
+### Route configuration options
+
+| Property | Type | Description |
+| -------- | ---- | ----------- |
+| `route` | String | URL path (supports Express route params like `/:_id`) |
+| `handlers` | Object | Map of HTTP method to handler function(s) |
+| `permissions` | Object | Map of HTTP method to required permission scopes |
+| `modifying` | Boolean | Whether the route modifies data (affects `req.apiData.modifying`) |
+| `validate` | Boolean | Whether to validate request data (default: `true`) |
+| `collectionName` | String | Override the default collection for this route |
+| `schemaName` | String | Override the default schema for this route |
+| `meta` | Object | OpenAPI metadata for documentation |
+| `internal` | Boolean | Restrict route to internal requests only (i.e. `localhost`) |
+
+### Route-level middleware
+
+You can add middleware to specific routes by passing an array of handlers:
+
+```javascript
+{
+  route: '/secure',
+  handlers: {
+    post: [this.validateInput.bind(this), this.secureHandler.bind(this)]
+  }
+}
+```
+
+## Requests
+
+### How requests are handled
+
+When using the default route configuration, `AbstractApiModule` provides two built-in handlers:
+
+#### requestHandler 
+Handles standard CRUD operations (POST, GET, PUT, PATCH, DELETE). It automatically:
+1. Invokes the `requestHook` for any pre-processing
+2. Checks access permissions (before the operation for PUT/PATCH/DELETE, after for GET)
+3. Calls the appropriate database method based on the HTTP method
+4. Sanitises the response data to remove internal fields
+5. Returns the result with the appropriate status code (201 for POST, 200 for GET/PUT/PATCH, 204 for DELETE)
+
+#### queryHandler 
+Handles advanced queries via POST to `/query`. It supports:
+1. MongoDB query operators in the request body (e.g., `$or`, `$gt`, `$regex`)
+2. Pagination via `page` and `limit` query parameters
+3. Sorting via a `sort` query parameter (e.g., `{"createdAt": -1}`)
+4. Skipping results via a `skip` query parameter
+
+#### Pagination
+
+When querying collections, the response includes pagination headers:
+
+| Header | Description |
+| ------ | ----------- |
+| `X-Adapt-Page` | Current page number |
+| `X-Adapt-PageSize` | Number of items per page |
+| `X-Adapt-PageTotal` | Total number of pages |
+| `Link` | Navigation links (first, prev, next, last) |
+
+Configure default pagination in `adapt-authoring-api` config:
+
+```json
+{
+  "defaultPageSize": 100,
+  "maxPageSize": 250
+}
+```
+
+### Writing request handlers
+
+Request handlers follow the Express middleware pattern:
+
+```javascript
+async myHandler (req, res, next) {
+  try {
+    // Handle request
+    res.json(result)
+  } catch (e) {
+    next(e)
+  }
+}
+```
+
+### Accessing request data
+
+The `req.apiData` object contains various properties specific to your API which may come in useful when handling requests. [See this guide](request-response) for a full list of properties available on the `req`/`res` objects, including `apiData`.
+
+
+## Database operations
+
+> For more information on interacting with the database, please [see this guide](using-mongodb?id=using-abstractapimodule)
+
+`AbstractApiModule` provides the following methods for database operations:
+
+- `find`
+- `findOne`
+- `insert`
+- `update`
+- `updateMany`
+- `delete`
+- `deleteMany`
+
+These methods provide automatic data validation, caching, and lifecycle hooks in addition to the actual database operations without needing to duplicate that logic in every call.
+
+## Hooks
+
+> For more detailed information on Hooks, [see this guide](hooks).
+
+`AbstractApiModule` provides several useful hooks for customising behaviour both inside and outside of the API module. These hooks are automatically invoked by the `AbstractApiModule` code, so need no extra action. They provide a quick and easy way to interact with various important API activities, and are often the best way to extend your API with custom behaviours.
+
+See the table below for a list of hooks provided by the `AbstractApiModule` class:
+
+| Hook | When it fires | Mutable |
+| ---- | ------------- | ------- |
+| `requestHook` | When an API request is received | Yes |
+| `preInsertHook` | Before inserting a document | Yes |
+| `postInsertHook` | After inserting a document | No |
+| `preUpdateHook` | Before updating a document | Yes |
+| `postUpdateHook` | After updating a document | No |
+| `preDeleteHook` | Before deleting a document | No |
+| `postDeleteHook` | After deleting a document | No |
+| `accessCheckHook` | When checking access to a resource | No |
+
+### Using hooks
+
+```javascript
+import { Hook } from 'adapt-authoring-core'
+import AbstractApiModule from 'adapt-authoring-api'
+
+class NotesModule extends AbstractApiModule {
+  async init () {
+    await super.init()
+    
+    /**
+     * Custom hook fired when a note is archived
+     * @type {Hook}
+     */
+    this.archivedHook = new Hook()
+    
+    // Add timestamps when creating documents
+    this.preInsertHook.tap(data => {
+      data.createdAt = new Date().toISOString()
+    })
+  }
+  
+  async archive () {
+    // Do some archiving...
+
+    // Invoke custom hook, passing the archived note to any observers
+    await this.archivedHook.invoke(note)
+  }
+}
+```
+
+### Access control with accessCheckHook
+
+Use `accessCheckHook` to implement custom access control:
+
+```javascript
+this.accessCheckHook.tap(async (req, doc) => {
+  // Return true to allow access, false or undefined to deny
+  return doc.createdBy === req.auth.user._id.toString()
+})
+```
+
+## Overriding methods
+
+You can override database methods to customise behaviour:
+
+```javascript
+async insert (...args) {
+  // Custom logic before insert
+  const result = await super.insert(...args)
+  // Custom logic after insert
+  return result
+}
+```
+
+Note in the above example we call `super.insert`, which will preserve the original function's behaviour. We strongly recommend calling the super class' function like in your override, as you may encounter unexpected issues if you completely replace the existing functionality with your own.
+
+### Overriding getSchemaName
+
+A common candidate for override is `getSchemaName()`, as there are cases where you may need to dynamically select a schema based on the request data:
+
+```javascript
+async getSchemaName (data) {
+  if (data._type === 'special') {
+    return 'specialnote'
+  }
+  return this.schemaName
+}
+```
+
+## Permissions
+
+Routes are secured using permission scopes. The default routes use `read:<root>` and `write:<root>` scopes, which are perfectly acceptable and recommended in most cases. We would suggest choosing a different scope when your API endpoint(s) perform non-standard actions, and so using a custom scope would be more descriptive - e.g. `build:myfeature` for a build tool API, or `debug` for debugging functionality.
+
+> For more information on permissions, see [this guide](auth-permissions)
+
+### Custom permission scope
+
+Set `permissionsScope` to use a different scope:
+
+```javascript
+async setValues () {
+  this.root = 'notes'
+  this.permissionsScope = 'content'  // Uses read:content, write:content
+  this.useDefaultRouteConfig()
+}
+```
+
+### Per-route permissions
+
+Define permissions per route and HTTP method:
+
+```javascript
+{
+  route: '/admin',
+  handlers: { get: this.adminHandler.bind(this) },
+  permissions: { get: ['read:admin', 'read:notes'] }  // Requires both scopes
+}
+```
+
+## Caching
+
+`AbstractApiModule` includes a data cache to reduce database calls. Configure it in `conf/config.schema.json`:
+
+```json
+{
+  "enableCache": {
+    "type": "boolean",
+    "default": true
+  },
+  "cacheLifespan": {
+    "type": "number",
+    "default": 60000
+  }
+}
+```
+
+The cache is used automatically by the `find()` method.
+
+## Error handling
+
+Use the application's error system for consistent error responses:
+
+```javascript
+async myHandler (req, res, next) {
+  try {
+    const doc = await this.findOne({ _id: req.apiData.query._id })
+    if (doc.archived) {
+      return next(this.app.errors.UNAUTHORISED.setData({
+        reason: 'Cannot modify archived notes'
+      }))
     }
-  ];
+    // Continue processing
+  } catch (e) {
+    next(e)
+  }
 }
 ```
+
+Common errors from the API module:
+
+| Error | Description |
+| ----- | ----------- |
+| `NOT_FOUND` | Resource not found |
+| `UNAUTHORISED` | Access denied |
+| `TOO_MANY_RESULTS` | Query returned multiple results when one was expected |
+| `HTTP_METHOD_NOT_SUPPORTED` | HTTP method not supported for this route |
+
+## Writing documentation
+
+If you plan on making your module available to others, it is vital that you provide good quality documentation to explain how it works. The Adapt authoring tool documentation covers three areas: the code, the REST API, and custom user manual pages. See the links below for more information on each:
+
+- [JSDoc style guide](jsdoc-guide)
+- [API documentation guide](rest-api-guide)
+- [Developer manual](writing-documentation?id=developer-manual)

package/package.json

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

package/.github/workflows/labelled_prs.yml

@@ -1,16 +0,0 @@
-name: Add labelled PRs to project
-
-on:
-  pull_request:
-    types: [ labeled ]
-
-jobs:
-  add-to-project:
-    if: ${{ github.event.label.name == 'dependencies' }}
-    name: Add to main project
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/add-to-project@v0.1.0
-        with:
-          project-url: https://github.com/orgs/adapt-security/projects/5
-          github-token: ${{ secrets.PROJECTS_SECRET }}