Rest

A rest-adapter for Mongoose-Express applications

Install

yarn add q3-core-rest

Usage

Rest helps reduce the number of controller functions in your application. It also powers up your document and sub-document search and filtering capabilities with the popular api-query-params package. Moreover, it registers several middleware functions for handling authentication, validation and redaction out-of-the-box.

Schema options

To configure REST, simply add three options to your Mongoose schema.

1. restify: A string to indicate which HTTP options to enable (or use a wildcard for all);

2. collectionPluralName: The name of property to list documents in the Response payload;

3. collectionSingularName: The name of the property on single-resource calls in the Response payload.

Example

The sample would generate the REST endpoints documented below.

ExampleModel.js

const { Schema, model } = require('mongoose');

const ExampleSchema = new Schema({
    title: {
        type: String
        searchable: true,
        required: true,
    },
    description: {
        type: String,
    },
}, {
    restify: 'GET POST', // accepts PATCH, DELETE and PUT too
    collectionPluralName: 'examples', // often same as collection
    collectionSingularName: 'example',
});

module.exports = model('rest-examples', ExampleSchema)

Get all examples

GET api.com/rest-examples

The collection name is used in the URL. For the sake of brevity, we'll only document the most common queries available. For more information, consult api-query-params.

Query Parameters

Name	Type	Description
fields	string	Comma-delineated string of fields to include.
page	number	Sometimes referred to as "skip." Defaults to 1.
limit	number	Defaults to 25.
search	string	Will perform regex-style query on all "searchable" props.

200 Returns documents underneath the "collectionPluralName" value.

{
    total: 1,
    examples: [
        {
            name: 'First',
            description: 'This is a document',
        }
    ]
}

Create an example

POST api.com/rest-examples

All top-level properties in the schema are exposed to the API body unless set as "systemOnly." The validation of the schema is copied into a validation layer for Express using m2e-validator and express-validator.

Request Body

Name	Type	Description
title	string	The title of the example.
description	string	A brief blurb about it.

200

{
    "example": {
        "id": 1,
        "title": "Success!",
        "description": "Our first example together."
    }
}

422

{
    "errors": {
        "title": {
            "msg": "This is a required field",
        }
    }
}