# Rest

### 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`](https://www.npmjs.com/package/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.

{% code title="ExampleModel.js" %}

```javascript
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)

```

{% endcode %}

## Get all examples

<mark style="color:blue;">`GET`</mark> `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. |

{% tabs %}
{% tab title="200 Returns documents underneath the "collectionPluralName" value." %}

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

{% endtab %}
{% endtabs %}

## Create an example

<mark style="color:green;">`POST`</mark> `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.   |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}

{% tab title="422 " %}

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

{% endtab %}
{% endtabs %}