Renamed /users to /authors for Content API V2 (#10096)

refs #10061

- Made /authors endpoint available in Content API V2

core/server/api/v2/authors.js

@@ -0,0 +1,66 @@
+const Promise = require('bluebird');
+const common = require('../../lib/common');
+const models = require('../../models');
+const ALLOWED_INCLUDES = ['count.posts'];
+
+module.exports = {
+    docName: 'authors',
+
+    browse: {
+        options: [
+            'include',
+            'filter',
+            'fields',
+            'limit',
+            'status',
+            'order',
+            'page'
+        ],
+        validation: {
+            options: {
+                include: {
+                    values: ALLOWED_INCLUDES
+                }
+            }
+        },
+        permissions: true,
+        query(frame) {
+            return models.User.findPage(frame.options);
+        }
+    },
+
+    read: {
+        options: [
+            'include',
+            'filter',
+            'fields'
+        ],
+        data: [
+            'id',
+            'slug',
+            'status',
+            'email',
+            'role'
+        ],
+        validation: {
+            options: {
+                include: {
+                    values: ALLOWED_INCLUDES
+                }
+            }
+        },
+        permissions: true,
+        query(frame) {
+            return models.User.findOne(frame.data, frame.options)
+                .then((model) => {
+                    if (!model) {
+                        return Promise.reject(new common.errors.NotFoundError({
+                            message: common.i18n.t('errors.api.authors.notFound')
+                        }));
+                    }
+
+                    return model;
+                });
+        }
+    }
+};

core/server/api/v2/index.js

@@ -77,5 +77,9 @@ module.exports = {
 
     get slack() {
         return shared.pipeline(require('./slack'), localUtils);
+    },
+
+    get authors() {
+        return shared.pipeline(require('./authors'), localUtils);
     }
 };

core/server/api/v2/utils/serializers/output/authors.js

@@ -0,0 +1,25 @@
+const debug = require('ghost-ignition').debug('api:v2:utils:serializers:output:authors');
+const mapper = require('./utils/mapper');
+
+module.exports = {
+    browse(models, apiConfig, frame) {
+        debug('browse');
+
+        frame.response = {
+            authors: models.data.map(model => mapper.mapUser(model, frame)),
+            meta: models.meta
+        };
+
+        debug(frame.response);
+    },
+
+    read(model, apiConfig, frame) {
+        debug('read');
+
+        frame.response = {
+            authors: [mapper.mapUser(model, frame)]
+        };
+
+        debug(frame.response);
+    }
+};

core/server/api/v2/utils/serializers/output/index.js

@@ -61,5 +61,9 @@ module.exports = {
 
     get oembed() {
         return require('./oembed');
+    },
+
+    get authors() {
+        return require('./authors');
     }
 };

core/server/apps/amp/lib/router.js

@@ -64,7 +64,7 @@ function getPostData(req, res, next) {
     }
 
     // @NOTE: amp is not supported for static pages
-    helpers.entryLookup(urlWithoutSubdirectoryWithoutAmp, {permalinks, resourceType: 'posts'}, res.locals)
+    helpers.entryLookup(urlWithoutSubdirectoryWithoutAmp, {permalinks, query: {resource: 'posts'}}, res.locals)
         .then((result) => {
             if (result && result.entry) {
                 req.body.post = result.entry;

core/server/helpers/get.js

@@ -37,6 +37,9 @@ const RESOURCES = {
     pages: {
         alias: 'pages',
         resource: 'posts'
+    },
+    authors: {
+        alias: 'authors'
     }
 };
 
@@ -145,6 +148,13 @@ get = function get(resource, options) {
     const controller = api[apiVersion][RESOURCES[resource].alias] ? RESOURCES[resource].alias : RESOURCES[resource].resource;
     const action = isBrowse(apiOptions) ? 'browse' : 'read';
 
+    // CASE: no fallback defined e.g. v0.1 tries to fetch "authors"
+    if (!controller) {
+        data.error = i18n.t('warnings.helpers.get.invalidResource');
+        logging.warn(data.error);
+        return Promise.resolve(options.inverse(self, {data: data}));
+    }
+
     // Parse the options we're going to pass to the API
     apiOptions = parseOptions(this, apiOptions);
 

core/server/models/user.js

@@ -341,6 +341,7 @@ User = ghostBookshelf.Model.extend({
 
         // CASE: The `withRelated` parameter is allowed when using the public API, but not the `roles` value.
         // Otherwise we expose too much information.
+        // @TODO: the target controller should define the allowed includes, but not the model layer O_O (https://github.com/TryGhost/Ghost/issues/10106)
         if (options && options.context && options.context.public) {
             if (options.withRelated && options.withRelated.indexOf('roles') !== -1) {
                 options.withRelated.splice(options.withRelated.indexOf('roles'), 1);

core/server/services/routing/CollectionRouter.js

@@ -91,6 +91,10 @@ class CollectionRouter extends ParentRouter {
             order: this.order,
             permalinks: this.permalinks.getValue({withUrlOptions: true}),
             resourceType: this.getResourceType(),
+            query: {
+                alias: 'posts',
+                resource: 'posts'
+            },
             context: this.context,
             frontPageTemplate: 'home',
             templates: this.templates,

core/server/services/routing/PreviewRouter.js

@@ -20,7 +20,10 @@ class PreviewRouter extends ParentRouter {
     _prepareContext(req, res, next) {
         res.routerOptions = {
             type: 'entry',
-            resourceType: 'preview'
+            query: {
+                alias: 'preview',
+                resource: 'posts'
+            }
         };
 
         next();

core/server/services/routing/StaticPagesRouter.js

@@ -39,6 +39,10 @@ class StaticPagesRouter extends ParentRouter {
             filter: this.filter,
             permalinks: this.permalinks.getValue(),
             resourceType: this.getResourceType(),
+            query: {
+                alias: 'pages',
+                resource: 'posts'
+            },
             context: ['page']
         };
 

core/server/services/routing/TaxonomyRouter.js

@@ -54,7 +54,7 @@ class TaxonomyRouter extends ParentRouter {
             type: 'channel',
             name: this.taxonomyKey,
             permalinks: this.permalinks.getValue(),
-            data: {[this.taxonomyKey]: _.omit(RESOURCE_CONFIG.QUERY[this.taxonomyKey], ['alias', 'internal'])},
+            data: {[this.taxonomyKey]: _.omit(RESOURCE_CONFIG.QUERY[this.taxonomyKey], ['internal'])},
             filter: RESOURCE_CONFIG.TAXONOMIES[this.taxonomyKey].filter,
             resourceType: this.getResourceType(),
             context: [this.taxonomyKey],
@@ -70,7 +70,7 @@ class TaxonomyRouter extends ParentRouter {
     }
 
     getResourceType() {
-        return RESOURCE_CONFIG.QUERY[this.taxonomyKey].resource;
+        return RESOURCE_CONFIG.QUERY[this.taxonomyKey].alias;
     }
 
     getRoute() {

core/server/services/routing/assets/resource-config.js

@@ -10,8 +10,7 @@ module.exports.QUERY = {
         }
     },
     author: {
-        internal: true,
-        alias: 'users',
+        alias: 'authors',
         type: 'read',
         resource: 'users',
         options: {
@@ -20,7 +19,7 @@ module.exports.QUERY = {
         }
     },
     user: {
-        alias: 'users',
+        alias: 'authors',
         type: 'read',
         resource: 'users',
         options: {

core/server/services/routing/controllers/preview.js

@@ -14,20 +14,10 @@ module.exports = function previewController(req, res, next) {
         include: 'author,authors,tags'
     };
 
-    let resourceType = res.routerOptions.resourceType;
-
-    /**
-     * @TODO:
-     * Remove fallback to posts if we drop v0.1.
-     */
-    if (!api[resourceType]) {
-        resourceType = 'posts';
-    }
-
-    api[resourceType]
+    (api[res.routerOptions.query.alias] || api[res.routerOptions.query.resource])
         .read(params)
         .then(function then(result) {
-            const post = result[resourceType][0];
+            const post = (result[res.routerOptions.query.alias] || result[res.routerOptions.query.resource])[0];
 
             if (!post) {
                 return next();

core/server/services/routing/controllers/static.js

@@ -8,7 +8,7 @@ function processQuery(query, locals) {
     query = _.cloneDeep(query);
 
     // Return a promise for the api query
-    return api[query.resource][query.type](query.options);
+    return (api[query.alias] || api[query.resource])[query.type](query.options);
 }
 
 module.exports = function staticController(req, res, next) {
@@ -31,7 +31,7 @@ module.exports = function staticController(req, res, next) {
                     if (config.type === 'browse') {
                         response.data[name] = result[name];
                     } else {
-                        response.data[name] = result[name][config.resource];
+                        response.data[name] = result[name][config.alias] || result[name][config.resource];
                     }
                 });
             }

core/server/services/routing/helpers/entry-lookup.js

@@ -30,22 +30,14 @@ function entryLookup(postUrl, routerOptions, locals) {
         isEditURL = true;
     }
 
-    let resourceType = routerOptions.resourceType;
-
-    // @NOTE: v0.1 does not have a pages controller.
-    // @TODO: remove me when we drop v0.1
-    if (!api[resourceType]) {
-        resourceType = 'posts';
-    }
-
     /**
      * Query database to find entry.
      * @deprecated: `author`, will be removed in Ghost 3.0
      */
-    return api[resourceType]
+    return (api[routerOptions.query.alias] || api[routerOptions.query.resource])
         .read(_.extend(_.pick(params, 'slug', 'id'), {include: 'author,authors,tags'}))
         .then(function then(result) {
-            const entry = result[resourceType][0];
+            const entry = (result[routerOptions.query.alias] || result[routerOptions.query.resource])[0];
 
             if (!entry) {
                 return Promise.resolve();

core/server/services/routing/helpers/fetch-data.js

@@ -2,27 +2,31 @@
  * # Fetch Data
  * Dynamically build and execute queries on the API
  */
-const _ = require('lodash'),
-    Promise = require('bluebird'),
-    defaultPostQuery = {};
+const _ = require('lodash');
+const Promise = require('bluebird');
 
 // The default settings for a default post query
 const queryDefaults = {
     type: 'browse',
     resource: 'posts',
+    alias: 'posts',
     options: {}
 };
 
 /**
- * Default post query needs to always include author, authors & tags
- *
  * @deprecated: `author`, will be removed in Ghost 3.0
  */
-_.extend(defaultPostQuery, queryDefaults, {
+const defaultQueryOptions = {
     options: {
         include: 'author,authors,tags'
     }
-});
+};
+
+/**
+ * Default post query needs to always include author, authors & tags
+ */
+const defaultPostQuery = _.cloneDeep(queryDefaults);
+defaultPostQuery.options = defaultQueryOptions.options;
 
 /**
  * ## Process Query
@@ -39,7 +43,6 @@ function processQuery(query, slugParam, locals) {
 
     query = _.cloneDeep(query);
 
-    // Ensure that all the properties are filled out
     _.defaultsDeep(query, queryDefaults);
 
     // Replace any slugs, see TaxonomyRouter. We replace any '%s' by the slug
@@ -48,7 +51,7 @@ function processQuery(query, slugParam, locals) {
     });
 
     // Return a promise for the api query
-    return api[query.resource][query.type](query.options);
+    return (api[query.alias] || api[query.resource])[query.type](query.options);
 }
 
 /**
@@ -100,7 +103,7 @@ function fetchData(pathOptions, routerOptions, locals) {
                     if (config.type === 'browse') {
                         response.data[name] = results[name];
                     } else {
-                        response.data[name] = results[name][config.resource];
+                        response.data[name] = results[name][config.alias] || results[name][config.resource];
                     }
                 });
             }

core/server/services/settings/validate.js

@@ -48,7 +48,6 @@ _private.validateData = function validateData(object) {
 
         let [resourceKey, slug] = shortForm.split('.');
 
-        // @NOTE: `data: author.foo` is not allowed currently, because this will make {{author}} available in the theme, which is deprecated (single author usage)
         if (!RESOURCE_CONFIG.QUERY[resourceKey] ||
             (RESOURCE_CONFIG.QUERY[resourceKey].hasOwnProperty('internal') && RESOURCE_CONFIG.QUERY[resourceKey].internal === true)) {
             throw new common.errors.ValidationError({
@@ -58,7 +57,7 @@ _private.validateData = function validateData(object) {
         }
 
         longForm.query[options.resourceKey || resourceKey] = {};
-        longForm.query[options.resourceKey || resourceKey] = _.omit(_.cloneDeep(RESOURCE_CONFIG.QUERY[resourceKey]), 'alias');
+        longForm.query[options.resourceKey || resourceKey] = _.cloneDeep(RESOURCE_CONFIG.QUERY[resourceKey]);
 
         // redirect is enabled by default when using the short form
         longForm.router = {
@@ -148,6 +147,7 @@ _private.validateData = function validateData(object) {
             });
 
             const DEFAULT_RESOURCE = _.find(RESOURCE_CONFIG.QUERY, {resource: data.query[key].resource});
+            data.query[key] = _.defaults(data.query[key], _.omit(DEFAULT_RESOURCE, 'options'));
 
             data.query[key].options = _.pick(object.data[key], allowedQueryOptions);
             if (data.query[key].type === 'read') {

core/server/services/url/Resources.js

@@ -109,7 +109,7 @@ const resourcesConfig = [
         }
     },
     {
-        type: 'users',
+        type: 'authors',
         modelOptions: {
             modelName: 'User',
             exclude: [

core/server/translations/en.json

@@ -349,6 +349,9 @@
             "posts": {
                 "postNotFound": "Post not found."
             },
+            "authors": {
+                "notFound": "Author not found."
+            },
             "pages": {
                 "pageNotFound": "Page not found."
             },