@tryghost/express-bookshelf-jsonapi 0.3.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2016 Hannah Wolfe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,164 @@
+# express-bookshelf-jsonapi
+_ebja for short - yep this module needs a better name, that's why it's still under my username_
+
+**WARNING: This is still very much a work in progress**
+
+ebja can be used to create API endpoints which:
+
+1. respond on express routes (act as middleware)
+2. serialise a bookshelf model as a response (even if it also does other work)
+3. use the JSONAPI format for request / responses
+
+ebja assumes that endpoints need to be extremely customisable. It has lots of sensible defaults but tries to make everything overridable, whilst still making it very easy to return full JSONAPI-compliant responses.
+
+## Example Usage
+
+```js
+var app = express();
+
+var jsonapi = ebja({
+    baseUrl: 'http://localhost:80/api',
+    models: require('./my-bookshelf-models')
+});
+var blogs = jsonapi.Resource({
+  model: 'Blog'
+});
+
+blogs.read = blogs.Endpoint({});
+
+app.get('/blogs/:id', blogs.read)
+```
+
+## ebja()
+
+The intial usage of ebja is to setup the initial config for your API.
+
+```js
+var jsonapi = ebja({
+    baseUrl: 'http://localhost:80/api',
+    models: require('./my-bookshelf-models')
+});
+```
+
+`ebja()` takes an options object with two parameters:
+* `baseUrl` - the url to prefix each endpoint with, for outputting in JSONAPI links
+* `models` - an object with model names as keys, and bookshelf models as values
+
+Once setup, the resulting object has two methods:
+* `Resource({})` - define a resource for which endpoints will be created, e.g. a Blogs resource for creating various CRUD endpoints (returns a resource)
+* `Endpoint({})` - define an endpoint without first creating a resource (returns a middleware function)
+
+`Resource` & `Endpoint` both take all the same options.
+A `Resource` has an `Endpoint` method which has all options passed to the resource as overridable defaults.
+
+Resources are a convenience for packaging up options for a group of endpoints, E.g. setting the model, permissions and configuring the response across a full suite of CRUD endpoints.
+
+## Principles
+
+#### Bookshelf plugin
+
+ebja assumes you'll wire up its bookshelf plugin. This provides access to two special model methods:
+
+* `getOne` - return a single resource
+* `getPage` - return a collection
+
+Both of these methods are used by ebja by default, to ensure that the JSONAPI params `include`, `page`, `sort`, `field` and `filter` are passed through to the model correctly and applied.\*
+
+```js
+var knex = require('knex')(dbConfig)
+var Bookshelf = require('bookshelf')(knex);
+
+Bookshelf.plugin(require('ebja').plugin);
+```
+
+\* Note: the params `field` and `filter` are currently disabled by this module. The params are only utilised in GET / query type endpoints.
+
+
+#### Endpoint "types"
+
+ebja works on the idea that there are 3 main types of endpoint:
+- query (method: GET) - default
+- action (methods: POST, PUT or PATCH)
+- destroy (method: DELETE)
+
+**Query** endpoints perform a fetch for a single object or collection with support for the JSONAPI params `include`, `page`, `sort`, `field` and `filter`.
+
+**Action** endpoints assume there is some operation to perform, e.g. to add or update a model. These endpoints usually perform a `getOne` query after the operation in order to return a serialised model in JSONAPI format.
+
+**Destroy** endpoints assume they are deleting a resource. They return a 204 and empty response by default on success.
+
+By setting the `method` option for an endpoint, the type of endpoint can be changed.
+
+#### Function "stacks" (apiware)
+
+For each type of endpoint (query, action, destroy) ebja has a stack of functions, much like middleware, that it will execute (see the Stacks listing below for details). Some stack functions have default behaviour, some are noops intended to be overridden with custom behaviour, e.g. `permissions`. These functions are referred to as apiware.
+
+Calling Endpoint() results in a function which can be called as express middleware. When called as middleware, the http `req` and `res` parameters are converted into transport-agnostic `APIRequest` and `APIResponse` objects. The apiware functions operate the same as express middleware, with the `APIRequest` and `APIResponse` object being past to each in turn, and each function calling `next()` to continue.
+
+For example, for a destroy endpoint there are just 2 apiware functions in the stack: `permissions()` (a noop) and `destroy()`. All 3 types of endpoint have a `permissions()` function just before the main operation. This function can be overridden by passing a function as a `permission` option to the Endpoint or Resource. All stack functions can be overridden in the same way.
+
+Example:
+
+```js
+var usersRead = jsonapi.Endpoint({
+    method: 'GET', // this is the default
+    queryMethod: 'getOne', // this is the default
+    model: 'User',
+    permissions: function (apiReq, apiRes, next) {
+      // If the id parameter in the url (query.data.id) matches the authenticated user (source.id)
+      if (apiReq.query.data.id === apiReq.source.id) {
+          // We're safe to continue because we are allowed access to this resource
+          return next();
+      }
+
+      // Else, we have no permission to continue
+      return next(new Error('NoPermissionError');
+    }
+});
+
+```
+
+## Options
+
+* `method` (default: `GET`) the HTTP method of the endpoint
+* `queryMethod` (default: `getOne`) the method to call on the model in the query apiware (query & action endpoints)
+* `actionMethod` (default: `noop`) the method to call on the model in the action apiware (action endpoints only)
+* `destroyMethod` (default: `destroy`) the method to call on the model in the destroy apiware (destroy endpoints only)
+* `relations` array of relations that the endpoint can `include`
+* `defaultSort` the default sort order
+* `<apiwarename>` all apiware functions can be overridden by providing a function with the same name to the options
+* `response` an object containing options for configuring the response
+   * `type` a string type to return in the JSONAPI response
+   * `attributes` whitelist
+   * any other option supported by [jsonapi-serializer](https://github.com/SeyZ/jsonapi-serializer#serialization) or [jsonapi-mapper](https://github.com/scoutforpets/jsonapi-mapper#api)
+
+
+## Stacks
+
+#### Query (default)
+
+* validate (noop)
+* paramsData
+* paramsInclude
+* paramsPage
+* paramsFilter
+* paramsFields
+* paramsSort
+* permissions (noop)
+* query (main operation)
+* process (noop)
+* format
+
+#### Action
+
+* validate (noop)
+* payload
+* permissions (noop)
+* action (main operation)
+* query (secondary operation)
+* process (noop)
+* format
+
+#### Destroy
+* permissions (noop)
+* destroy (main operation)

package/index.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('./lib/ebja');

package/lib/api.js

@@ -0,0 +1,41 @@
+'use strict';
+
+var debug = require('ghost-ignition').debug('api');
+var _ = require('lodash');
+var Endpoint = require('./endpoint');
+var Resource = require('./resource');
+
+// Declare our API top-level object
+var api = exports = module.exports = {};
+
+api.init = function init(options) {
+    debug('initing api');
+
+    if (!options) {
+        throw new Error('EBJA requires configuration');
+    }
+
+    if (!options.baseUrl) {
+        throw new Error('EBJA requires a baseUrl');
+    }
+
+    if (!options.models) {
+        throw new Error('EBJA requires bookshelf models');
+    }
+
+    this.baseUrl = options.baseUrl;
+    this.models = options.models;
+
+    delete options.baseUrl;
+    delete options.models;
+
+    this.options = _.defaults({}, options, {request: {}, response: {}});
+};
+
+api.Resource = function registerResource(options) {
+    return new Resource(this, options);
+};
+
+api.Endpoint = function registerEndpoint(options) {
+    return new Endpoint(this, options);
+};

package/lib/apiware/action.js

@@ -0,0 +1,47 @@
+var debug = require('ghost-ignition').debug('apiware:action');
+var errors = require('ghost-ignition').errors;
+var _ = require('lodash');
+
+/**
+ * Action
+ *
+ * Default behaviour: takes a method & sends the payload to it
+ */
+module.exports = function action(apiReq, apiRes, next) {
+    // If there's no actionMethod defined, then this is a noop
+    if (!apiReq.options.actionMethod) {
+        debug('doing noop');
+        return next();
+    }
+
+    var methodToCall = apiReq.options.actionMethod;
+    debug('doing model actionMethod', methodToCall);
+
+    var actionPayload = _.clone(apiReq.query.data);
+    // We've used data, so we clear it from apiReq.query
+    apiReq.query.data = {};
+
+    if (apiReq.params.identifier) {
+        actionPayload.id = apiReq.params.identifier;
+    }
+
+    apiRes.exec.push({
+        method: methodToCall,
+        payload: actionPayload
+    });
+
+    return apiReq.model[methodToCall](actionPayload)
+        .then(function actionSuccess(result) {
+            debug('Success!', result.id);
+            apiReq.query.data.id = result.id;
+
+            return next();
+        }, function actionFailure(err) {
+            if (err instanceof apiReq.model.NotFoundError || err instanceof apiReq.model.NoRowsUpdatedError) {
+                return next(new errors.NotFoundError({message: 'Resource Not Found'}));
+            }
+
+            debug('model action failed');
+            return next(err);
+        });
+};

package/lib/apiware/destroy.js

@@ -0,0 +1,35 @@
+var debug = require('ghost-ignition').debug('apiware:destroy');
+var errors = require('ghost-ignition').errors;
+
+module.exports = function destroy(apiReq, apiRes, next) {
+    if (!apiReq.params.identifier) {
+        return next(new errors.BadRequestError({message: 'Attempting to destroy a resource without an identifier'}));
+    }
+
+    // Default to looking for a method called destroy
+    var methodToCall = apiReq.options.destroyMethod || 'destroy';
+
+    var destroyPayload = {
+        id:  apiReq.params.identifier,
+        require: true
+        // @TODO make it possible to pass through through a transaction
+    };
+
+    apiRes.exec.push({
+        method: methodToCall,
+        payload: destroyPayload
+    });
+
+    return apiReq.model[methodToCall](destroyPayload)
+        .then(function destroySuccess() {
+            debug('Success!');
+            return next();
+        }, function destroyFailure(err) {
+            if (err instanceof apiReq.model.NoRowsDeletedError) {
+                return next(new errors.NotFoundError({message: 'Resource Not Found'}));
+            }
+
+            debug('model destroy failed');
+            return next(err);
+        });
+};

package/lib/apiware/format.js

@@ -0,0 +1,54 @@
+var debug = require('ghost-ignition').debug('apiware:format');
+
+function updateRelations(model, relation) {
+    if (model.relations && !model.relations[relation]) {
+        // Simulating an empty collection in json-mapper
+        model.relations[relation] = {toJSON: function toJSON() { 
+            return relation.match(/s$/) ? [] : {};
+        }};
+    }
+}
+
+function ensureRelationLinksArePresent(relations, apiRes) {
+    if (relations) {
+        // Update mapper options so that these are output
+        apiRes.mapperOptions.relations = {
+            fields: relations, included: true
+        };
+
+        // Update model, this is a hack to work around https://github.com/scoutforpets/jsonapi-mapper/issues/69
+        // That is, there's no other way to tell the mapper to include relations
+        relations.forEach(function addRelationToModel(relation) {
+            if (apiRes.model.length) {
+                // This is a collection
+                apiRes.model.forEach(function (model) {
+                    updateRelations(model, relation)
+                });
+            } else {
+                updateRelations(apiRes.model, relation);
+            }
+        });
+
+        // If serializerOptions.attributes is set, we need to merge the relations into the list to ensure
+        // That these are also output, else we have to duplicate the definition of them
+        if (apiRes.serializerOptions.attributes) {
+            apiRes.serializerOptions.attributes = apiRes.serializerOptions.attributes.concat(relations);
+        }
+    }
+}
+
+// @TODO think about how to restructure this
+// So that there is default behaviour, which is overridable / extensible
+// Rather than having to wholesale replace this function
+module.exports = function format(apiReq, apiRes, next) {
+    debug('compiling mapper options');
+    var relations = apiReq.options.relations;
+    ensureRelationLinksArePresent(relations, apiRes);
+
+    // Ensure we get pagination from the model
+    if (apiRes.model && apiRes.model.pagination) {
+        apiRes.mapperOptions.pagination = apiRes.model.pagination;
+    }
+
+    next();
+};

package/lib/apiware/index.js

@@ -0,0 +1,76 @@
+var queue = exports;
+
+/**
+ * Query GET "queue"
+ *
+ * - Validate = run any validations defined (how to define these?!)
+ * - Params = run through all the params items, each with some config?
+ * - Permissions = defined by the calling module / default concept of ownership
+ * - Query = execute the modelMethod to collect the data to return
+ * - Process = clean up the model data, post permissions, etc
+ * - Format = prepare for mapper/formatter
+ */
+queue.query = {
+    // Validate: no-op until we have a standard definition
+    validate: require('./noop'),
+    // Params: there's a bunch of these!
+    // TODO: we need an efficient way to run them all
+    // TODO: and a simple way to hook into each one to override behaviour / define if it is enabled or not
+    paramsData: require('./params-data'), // this should probably have a different name?
+    paramsInclude: require('./params-include'),
+    paramsPage: require('./params-page'),
+    paramsFilter: require('./params-filter'),
+    paramsFields: require('./params-fields'),
+    paramsSort: require('./params-sort'),
+    // Permissions: noop until we have a default concept of ownership
+    permissions: require('./noop'),
+    // Query: execute a modelMethod to get data to return
+    query: require('./query'),
+    // Process: noop
+    process: require('./noop'),
+    // Format: prepare options to be passed to the formatter
+    format: require('./format')
+};
+
+/**
+ * Action POST/PUT/PATCH "queue"
+ *
+ * - Validate = run any validations defined (how to define these?!)
+ * - Permissions = defined by the calling module / default concept of ownership
+ * - Action = defined by the calling module
+ * - Query = execute the modelMethod to collect the data to return
+ * - Process = clean up the model data, post permissions, etc
+ * - Format = prepare for mapper/formatter
+ */
+queue.action = {
+    // Validate: no-op until we have a standard definition
+    validate: require('./noop'),
+    // Payload: process req.body
+    payload: require('./payload'),
+    // Permissions: noop until we have a default concept of ownership
+    permissions: require('./noop'),
+    // Action: noop unless defined by the calling module
+    action: require('./action'),
+    // Query: execute a modelMethod to get data to return
+    query: require('./query'),
+    // Process: noop
+    process: require('./noop'),
+    // Format: prepare options to be passed to the formatter
+    format: require('./format')
+};
+
+
+/**
+ * DELETE "queue"
+ *
+ * - Permissions = defined by the calling module / default concept of ownership
+ * - Query = execute the modelMethod to delete
+ * END -> return error or 204 No Content
+ */
+
+queue.destroy = {
+    // Permissions: noop until we have a default concept of ownership
+    permissions: require('./noop'),
+    // Destroy: execute destroy or destroyMethod if set to remove data
+    destroy: require('./destroy')
+};

package/lib/apiware/noop.js

@@ -0,0 +1,5 @@
+var debug = require('ghost-ignition').debug('apiware:noop');
+module.exports = function noop(apiReq, apiRes, next) {
+    debug('doing no op');
+    next();
+};

package/lib/apiware/params-data.js

@@ -0,0 +1,12 @@
+var debug = require('ghost-ignition').debug('apiware:paramsData');
+
+module.exports = function paramsData(apiReq, apiRes, next) {
+    debug('Checking for identifier');
+    if (apiReq.params.identifier) {
+        // Handle having an ID
+        debug('Handling identifier');
+        apiReq.query.data.id = apiReq.params.identifier;
+    }
+
+    next();
+};

package/lib/apiware/params-fields.js

@@ -0,0 +1,14 @@
+var debug = require('ghost-ignition').debug('apiware:paramsFields');
+var errors = require('ghost-ignition').errors;
+var _ = require('lodash');
+
+module.exports = function paramsFields(apiReq, apiRes, next) {
+    debug('Fields is not yet supported');
+
+    if (!_.isEmpty(apiReq.params.queryData.fields)) {
+        return next(new errors.BadRequestError({message: 'Fields is not yet supported'}));
+    }
+
+    apiReq.query.options.fields = {};
+    return next();
+};

package/lib/apiware/params-filter.js

@@ -0,0 +1,23 @@
+var debug = require('ghost-ignition').debug('apiware:paramsFilter');
+var errors = require('ghost-ignition').errors;
+var _ = require('lodash');
+
+module.exports = function paramsFilter(apiReq, apiRes, next) {
+    debug('Filter is not yet supported');
+    var filterIsEmpty = true;
+
+    // @TODO, yep this is dumb, waiting for jsonapi-mapper & bookshelf-jsonapi-params to come out of beta
+    // @TODO, figure out what we should support here
+    _.each(apiReq.params.queryData.filter, function (filter) {
+        if (!_.isEmpty(filter)) {
+            filterIsEmpty = false;
+        }
+    });
+
+    if (!filterIsEmpty) {
+        return next(new errors.BadRequestError({message: 'Filter is not yet supported'}));
+    }
+
+    apiReq.query.options.filter = {};
+    return next();
+};

package/lib/apiware/params-include.js

@@ -0,0 +1,22 @@
+var debug = require('ghost-ignition').debug('apiware:paramsInclude');
+var errors = require('ghost-ignition').errors;
+var _ = require('lodash');
+
+module.exports = function paramsInclude(apiReq, apiRes, next) {
+    // Handle Includes
+    var requestedIncludes = apiReq.params.queryData.include;
+    var allowedIncludes = apiReq.options.relations;
+    var diff = _.difference(requestedIncludes, allowedIncludes);
+    debug('permitting includes', allowedIncludes);
+
+    if (diff.length > 0) {
+        return next(new errors.ValidationError({
+            message: 'Unsupported include value',
+            source: diff.join(', ')
+        }));
+    }
+
+    apiReq.query.options.include = apiReq.params.queryData.include;
+
+    return next();
+};

package/lib/apiware/params-page.js

@@ -0,0 +1,36 @@
+var _ = require('lodash'),
+    debug = require('ghost-ignition').debug('apiware:paramsPage'),
+    defaultPageOptions = {
+        limit: 10,
+        offset: 0
+    };
+
+module.exports = function paramsPage(apiReq, apiRes, next) {
+    debug('Ensuring limit and offset');
+
+    if (apiReq.options.queryMethod === 'getOne') {
+        return next();
+    }
+
+    var pageOptions = apiReq.options.page || {};
+
+    if (pageOptions.pageSize) {
+        pageOptions.limit = pageOptions.pageSize;
+        delete pageOptions.pageSize;
+    }
+
+    if (pageOptions.page) {
+        pageOptions.offset = pageOptions.page;
+        delete pageOptions.page;
+    }
+
+    pageOptions = _.defaults({}, apiReq.params.queryData.page, pageOptions, defaultPageOptions);
+
+    if (pageOptions.limit === 'all') {
+        pageOptions = false;
+    }
+
+    apiReq.query.options.page = pageOptions;
+
+    return next();
+};

package/lib/apiware/params-sort.js

@@ -0,0 +1,16 @@
+var debug = require('ghost-ignition').debug('apiware:paramsSort');
+var _ = require('lodash');
+
+module.exports = function paramsSort(apiReq, apiRes, next) {
+    debug('Sorting');
+
+    // Apply the default
+    apiReq.query.options.sort = apiReq.options.defaultSort || [];
+
+    if (!_.isEmpty(apiReq.params.queryData.sort)) {
+        // If a sort was set for this request, apply that instead
+        apiReq.query.options.sort = apiReq.params.queryData.sort;
+    }
+
+    return next();
+};

package/lib/apiware/payload.js

@@ -0,0 +1,52 @@
+var errors = require('ghost-ignition').errors;
+var _ = require('lodash');
+
+function isValidData(data) {
+    if (_.isEmpty(data)) {
+        return false;
+    }
+
+    if (!_.isArray(data) && !_.isObject(data)) {
+        return false;
+    }
+
+    if (_.isArray(data)) {
+        // TODO: validate collections / arrays
+        return true;
+    }
+
+    if (!_.has(data, 'type')) {
+        return false;
+    }
+
+    if (!_.has(data, 'attributes')) {
+        return false;
+    }
+
+    return true;
+}
+
+module.exports = function payload(apiReq, apiRes, next) {
+    if (!_.isEmpty(apiReq.payload)) {
+        var data = apiReq.payload.data;
+        // Handle having a payload
+        if (!isValidData(data)) {
+            return next(new errors.BadRequestError({
+                message: 'Malformed payload: data object is invalid'
+            }));
+        }
+
+        if (_.isArray(data) && data.length === 1) {
+            apiReq.query.data = data[0].attributes;
+        }
+
+        // TODO handle array payloads with more than 1 item?
+
+        // Arrays return true for isObject :(
+        if (!_.isArray(data) && _.isObject(data)) {
+            apiReq.query.data = data.attributes;
+        }
+    }
+
+    next();
+};

package/lib/apiware/query.js

@@ -0,0 +1,28 @@
+var debug = require('ghost-ignition').debug('apiware:query');
+var errors = require('ghost-ignition').errors;
+
+module.exports = function query(apiReq, apiRes, next) {
+    // Default to using the getOne method
+    var methodToCall = apiReq.options.queryMethod || 'getOne';
+
+    debug('doing model queryMethod', methodToCall);
+
+    apiRes.exec.push({
+        method: methodToCall,
+        payload: apiReq.query
+    });
+
+    apiReq.model[methodToCall](apiReq.query)
+        .then(function querySuccess(result) {
+            debug('model query succeeded');
+            apiRes.model = result;
+            return next();
+        }, function queryFailure(err) {
+            if (err instanceof apiReq.model.NotFoundError) {
+                return next(new errors.NotFoundError({message: 'No result found'}));
+            }
+
+            debug('model query failed');
+            return next(err);
+        });
+};