Lorem Ipsum
", "extended": "Dolor sit amet
" }, "state": "draft" }, { "_id": "54e2f411a21780d7a097ce8e", "title": "Just a small Test", "publishedDate": "2015-02-16T23:00:00.000Z", "author": null, "categories": [], "content": { "brief": "This is a test
", "extended": "To make sure restful-keystone is functioning correctly
" }, "state": "published" } ] } ``` By default it will setup these routes: * `GET /api/This is a test
", "extended": "To make sure restful-keystone is functioning correctly
" }, "state": "published" } } ``` When you pass it a **plain string** it will be used as-is: ```js restful.expose({ Article : { envelop: "results" } }); ``` Will envelop all request results in `"results"`: ```sh GET /api/articles Status: 200 OK { results: [ // articles ] } ``` If however, you pass it an ERB-style interpolate delimiter string it will be substituted with whatever list or configuration value you want. E.g. ```js restful.expose({ Article : { envelop: "<%=path%>" } }); ``` Will envelop all results (even those of requests on single resources) in a field with the same name as the `path` value of the list, e.g. `"articles"`: ```sh GET /api/articles/54e2f411a21780d7a097ce8e Status: 200 OK { "articles": { "_id": "54e2f411a21780d7a097ce8e", "title": "Just a small Test", "publishedDate": "2015-02-16T23:00:00.000Z", "author": null, "categories": [], "content": { "brief": "This is a test
", "extended": "To make sure restful-keystone is functioning correctly
" }, "state": "published" } } ``` **You can turn enveloping off altogether by passing it a boolean `false`.** ##### `filter` **{Object}** You can set permanent filtering on a collection with `filter`. Pass it any key/value pair to automatically restrict all operations to documents that pass the condition. ```js restful.expose({ Article : { filter : { state: "published" } } }); ``` Will only operate on Article documents that have a `"published"` value in `"state"`. ##### `populate` **{Boolean|String|String[]}** default: `false` Allows automatic population of relationship fields. ```js restful.expose({ Article : { populate : "author" } }); ``` ```sh GET /api/articles/54e2f411a21780d7a097ce8e Status: 200 OK { "article": { "_id": "54e2f3d7a21780d7a097ce8d", "title": "Lorem Ipsum", "author": { "_id": "543f8abd6f0a6bb721653954", "name": { "last": "User", "first": "Admin", "full": "Admin User" }, "email": "admin@d-pac.be" }, "content": { "brief": "Lorem Ipsum
", "extended": "Dolor sit amet
" } } } ``` ##### `path` **{String}** default: the plural name of the list Allows you to configure the path at which the resources will be expose. ```js restful.expose({ Article : { path : "news" } }); ``` ```sh GET /api/news/54e2f411a21780d7a097ce8e Status: 200 OK { "article": { "_id": "54e2f3d7a21780d7a097ce8d", "title": "Lorem Ipsum", "author": { "_id": "543f8abd6f0a6bb721653954", "name": { "last": "User", "first": "Admin", "full": "Admin User" }, "email": "admin@d-pac.be" }, "content": { "brief": "Lorem Ipsum
", "extended": "Dolor sit amet
" } } } ``` #### `before` and `after` `before` and `after` allow you to register middleware functions that are executed ... umm ... before and after the response creation. Obviously this could be achieved by using the usual `app.get("/api/articles", someMiddleware)` as well, but these methods allow you to configure it by list name instead of path. ```js restful.expose({ Article: true }).before({ Article: requireAdmin }); ``` This will call the `requireAdmin` middleware function before the response is generated, for any of the methods: "retrieve", "list", ... Obviously you can configure it to be executed for specific methods only: ```js restful.expose({ Article: true }).before({ Article: { update: requireAdmin, remove: [requireAdmin, resourceExists], create: [requireAdmin, limitNotReached] } }); ``` Either provide the middleware by method as in the above example, but if you want to execute the same middleware on several methods at once you can pass them separately: ```js restful.expose({ Article: true }).before("update remove create", { Article: requireAdmin }); ``` This will execute `requireAdmin` only for the "update", "remove" and "create" methods (i.e. not for "list" and "retrieve") As you saw in the above examples you can pass a function or an array of functions in all occasions. Multiple calls to `before` (or `after`) will merge the configurations: ```js restful.expose({ Article: true }).before("update remove create", { Article: requireAdmin }).before("update", { Article: requireAllFields }); ``` Will execute `requireAdmin` and `requireAllFields` for the "update" method. **`after` behaves identical to `before` except for one thing:** By default restful-keystone will send the response, but any method that receives `after` middleware will have to have additional middleware to send the response. This is to allow maximum flexibility, otherwise you wouldn't be able to manipulate the results before they're sent. ```js restful.expose({ Article: true }).after("create", { Article: function(req, res, next){ console.log("CREATED:", res.locals.body); res.send(res.locals.status, res.locals.body); } }); ``` As you can see the response and status code are stored in `res.locals` #### start This signals to restful-keystone that it should set up the routes et cetera. I.e. you're finished configuring. ```js restful.expose({ Article: true }).after("create", { Article: function(req, res, next){ console.log("CREATED:", res.locals.body); res.send(res.locals.status, res.locals.body); } }).start(); // DO NOT FORGET TO START restful-keystone ``` A `start` method was added to allow you to configure restful in any order you see fit, i.e. this is all possible: ``` restful.before( /* config */ ) .expose( /* config */ ) .after( /* config */ ) .start(); ``` Or ``` restful .after( /* config */ ) .expose( /* config */ ) .before( /* config */ ) .start(); ``` Just make sure `start` is the last method to be called. ### Requests All values can be passed with requests as `json` bodies or as url encoded json over the query string. ```sh PATCH /api/articles/54e2f411a21780d7a097ce8e { "title": "Changed my title!" } Status: 200 OK { "article": { "_id": "54e2f3d7a21780d7a097ce8d", "title": "Changed my title!", "author": "543f8abd6f0a6bb721653954", "content": { "brief": "Lorem Ipsum
", "extended": "Dolor sit amet
" } } } ``` Is equivalent to: ```sh PATCH /api/articles/54e2f411a21780d7a097ce8e?%7B%0D%0A%09%22title%22%3A+%22Changed+my+title%21%22%0D%0A%7D Status: 200 OK { "article": { "_id": "54e2f3d7a21780d7a097ce8d", "title": "Changed my title!", "author": "543f8abd6f0a6bb721653954", "content": { "brief": "Lorem Ipsum
", "extended": "Dolor sit amet
" } } } ``` `list` requests allow the passing of a `filter` value in order to do on-the-fly filtering, see above for an explanation. ### Responses All requests respond with a `200 OK` status if the request was succesful, except for `remove` requests which will return `204 No Content`. When something goes wrong appropriate errors are thrown, however restful-keystone does not provide any error handling out of the box, i.e. you need to make sure you have some kind of error handling middleware in place. ### Permissions restful-keystone does **NOT** provide any security checks, i.e. if you expose a resource it is available to anonymous requests !! You need to set up any restrictions you want to see applied to routes yourself. ## Roadmap * Configuration through `json` files * Optional full adherence to jsonapi.org spec * Pagination ## Changelog * **v0.1** make compatible with Keystone v0.3 (i.e. express 4) * **v0.2** * API improvements * added `before` and `after` hooks * **v0.1** initial API ## License MIT © [d-pac](http://www.d-pac.be) MIT © [woflow](https://github.com/WofloW) [npm-url]: https://npmjs.org/package/restful-keystone [npm-image]: https://badge.fury.io/js/restful-keystone.svg [travis-url]: https://travis-ci.org/d-pac/restful-keystone [travis-image]: https://travis-ci.org/d-pac/restful-keystone.svg?branch=master [daviddm-url]: https://david-dm.org/d-pac/restful-keystone.svg?theme=shields.io [daviddm-image]: https://david-dm.org/d-pac/restful-keystone --- _Source: https://npm.io/package/restful-keystone-adv · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._