Example of how to scaffold API endpoints for Posts in a Keystone project (based on the yo keystone example).

KeystoneApiExample.md

This is an example of how to scaffold API endpoints to list / get / create / update / delete Posts in a Keystone website.

It's a modification of the default project created with the yo keystone generator (see https://github.com/JedWatson/generator-keystone)

Gists don't let you specify full paths, so in the project structure the files would be:

routes-index.js        -->    /routes/index.js         // modified to add the api endpoints
routes-api-posts.js    -->    /routes/api/posts.js     // new file containing the Post API route controllers

It creates JSON endpoints for:

• /api/post/list - lists all posts
• /api/post/create - creates a new post
• /api/post/{id} - returns the details of posts by id
• /api/post/{id}/update - updates a post by id and returns the details
• /api/post/{id}/delete - deletes a post by id

The create and update routes accept either GET or POST requests for simplicity, and look in either the URL parameters of the request body for data using the same paths as set on the models.

You can add your own logic in for security, default values, limiting fields etc. by configuring the functions exported by /routes/api/posts.js

routes-api-posts.js

var async = require('async'),
	keystone = require('keystone');

var Post = keystone.list('Post');

/**
 * List Posts
 */
exports.list = function(req, res) {
	Post.model.find(function(err, items) {
		
		if (err) return res.apiError('database error', err);
		
		res.apiResponse({
			posts: items
		});
		
	});
}

/**
 * Get Post by ID
 */
exports.get = function(req, res) {
	Post.model.findById(req.params.id).exec(function(err, item) {
		
		if (err) return res.apiError('database error', err);
		if (!item) return res.apiError('not found');
		
		res.apiResponse({
			post: item
		});
		
	});
}


/**
 * Create a Post
 */
exports.create = function(req, res) {
	
	var item = new Post.model(),
		data = (req.method == 'POST') ? req.body : req.query;
	
	item.getUpdateHandler(req).process(data, function(err) {
		
		if (err) return res.apiError('error', err);
		
		res.apiResponse({
			post: item
		});
		
	});
}

/**
 * Get Post by ID
 */
exports.update = function(req, res) {
	Post.model.findById(req.params.id).exec(function(err, item) {
		
		if (err) return res.apiError('database error', err);
		if (!item) return res.apiError('not found');
		
		var data = (req.method == 'POST') ? req.body : req.query;
		
		item.getUpdateHandler(req).process(data, function(err) {
			
			if (err) return res.apiError('create error', err);
			
			res.apiResponse({
				post: item
			});
			
		});
		
	});
}

/**
 * Delete Post by ID
 */
exports.remove = function(req, res) {
	Post.model.findById(req.params.id).exec(function (err, item) {
		
		if (err) return res.apiError('database error', err);
		if (!item) return res.apiError('not found');
		
		item.remove(function (err) {
			if (err) return res.apiError('database error', err);
			
			return res.apiResponse({
				success: true
			});
		});
		
	});
}

routes-index.js

var _ = require('underscore'),
	keystone = require('keystone'),
	middleware = require('./middleware'),
	importRoutes = keystone.importer(__dirname);

// Common Middleware
keystone.pre('routes', middleware.initLocals);
keystone.pre('render', middleware.flashMessages);

// Import Route Controllers
var routes = {
	views: importRoutes('./views'),
	api: importRoutes('./api')
};

// Setup Route Bindings
exports = module.exports = function(app) {
	
	// Views
	app.get('/', routes.views.index);
	app.get('/blog/:category?', routes.views.blog);
	app.get('/blog/post/:post', routes.views.post);
	app.get('/gallery', routes.views.gallery);
	app.all('/contact', routes.views.contact);
	
	app.get('/api/post/list', keystone.initAPI, routes.api.posts.list);
	app.all('/api/post/create', keystone.initAPI, routes.api.posts.create);
	app.get('/api/post/:id', keystone.initAPI, routes.api.posts.get);
	app.all('/api/post/:id/update', keystone.initAPI, routes.api.posts.update);
	app.get('/api/post/:id/remove', keystone.initAPI, routes.api.posts.remove);
	
}

Is it possible to set up this for the User model, and use it to allow non-admin users to update their details?
Obviously there would need to be some extra security to only allow the user to edit their own details.

I had a quick go, but ran into a validation error saying "Passwords should match" - presumably there needs to be some encryption using bcrypt first? If this won't work, is there any other way of being able to do this. What about if the user wants to change their password? Allowing non-admin users to update their account details seems like a common thing to want to do, but I can't find any examples of this anywhere.

@jjhesk, have you tried @liming's solution of changing keystone.initAPI to keystone.middleware.api ? It worked for me.

Will this be natively available in 0.4?

I urgently need help with something, I created an example with a very simple list (of countries) and created api routes like instructed:

app.get('/api/countries', keystone.middleware.api, routes.api.countries.list);

import keystone from 'keystone';

export function list(req, res) {
  keystone.List('Country').model.find((err, items) => {
    if (err) return res.apiError('database error', err);

    res.apiResponse({
      countries: items
    });
  });
}

I get the error Cannot read property 'find' of undefined, the List object exists but it doesn't have a model property. Does anyone know why this is? The keystone admin UI works as expected and there are several objects in the database.

Update: I found the solution, the problem was that I used keystone.List (capitalized) instead of keystone.list. Hopefully someone else will be helped by this answer.

Anyone here to explain ?
Example of sending file (csv) ?

Hi there,

I'm having a hard time making my API work.
Models: I have a Destination model, with services attached to it, like this (in /models/Destination.js):

var Destination = new keystone.List('Destination', {
	map: { name: 'name' },
	track: true,
	nocreate: true,
	defaultSort: 'name',
});

Destination.add({
	/* Destination fields */
	name: { type: String, label: 'Nome', required: true, initial: true }, 
	code: { type: String, label: 'Codice', required: true, initial: true, index: true, unique: true, noedit: true }, 
	desc: { type: String, label: 'Descrizione'}
});

/**
 * Relationships
 */
Destination.relationship(
	{ path: 'hotels', ref: 'Service', refPath: 'destinationRef', filters: { serviceType: 'HO' }, many: true },
	{ path: 'bookings', ref: 'Booking', refPath: 'destinationRef' }
	);

I've built routes like this (in /routes/index.js):

	// public API
	app.all('/api*', keystone.middleware.api);
	app.get('/api/dest', keystone.middleware.api, routes.api.dest.getDestinations);
	app.get('/api/dest/:code', keystone.middleware.api, routes.api.dest.getDestinationByCode);

And finally I have my exported method in /api/dest.js, like this:

/**
 * Get Destination by code
 */
exports.getDestinationByCode = function(req, res) {
  var normCode = req.params.code.toUpperCase();
  // console.log("In API call: /api/dest/:code with "+normCode);

  Destination
    .model
    .where({'code': normCode})
/*    .populate({
      path: 'hotels',
      model: 'Service',
      select: 'code name overall',
      match: {
        'serviceType': 'HO'
      }
    })*/
    .populate('hotels')
    .select({'code': 1, 'name': 1, 'desc': 1})
    .findOne()
    .exec(function(err, item) {

      if (err) return res.apiError('database error', err);
      if (!item) return res.apiError('not found');

      res.apiResponse({
        collection: item
      });
    });
}

Now, what I receive back by calling /api/dest/:code is incomplete:
{"collection":{"_id":"59b424b5d7938827d40a755c","name":"Zanzibar","code":"ZNZ","desc":"Where Freddie Mercury was born!"}}
Where is my 'hotels' relationship? I do see relationships in AdminUI (almost as expected, 'filters' gets not respected though). But no matter what, the API call has no 'hotels' field. I've tried 'populate' in two versions (the alternative is the one commented above), I've tried using populateRelated, like this:

    ... .exec(function(err, item) {

      if (err) return res.apiError('database error', err);
      if (!item) return res.apiError('not found');

      item.populateRelated('hotels', function(err) {
        if (err) return res.apiError('populate error', err);
        console.log(item.hotels);
        // how do I use item.hotels??
      });

      res.apiResponse({
        collection: item
      });
...

This way, console.log shows me the correct list of result, but then I ran out of ideas about how to get back the result into returned item.

Can anyone help or suggest?
Running Keystone with DEBUG=keystone:* node keystone helped figure out a bit, but not enough.

Thanks in advance.
Filippo

---

**EDIT:
I've been able to hack this by manually populating the hotel list, like this:

exports.getDestinationByCode = function(req, res) {
  var normCode = req.params.code.toUpperCase();

  Destination
    .model
    .where({'code': normCode})
    .select({'code': 1, 'name': 1, 'desc': 1, '_id': 0})
    .findOne()
    .exec(function(err, item) {

      if (err) return res.apiError('database destination error', err);
      if (!item) return res.apiError('not found');

      Service
        .model
        .where({'destinationRef': item._id, 'serviceType': 'HO'})
        .select({'code': 1, 'name': 1, 'overall': 1, '_id': 0})
        .find(function(err, hotels) {

          if (err) return res.apiError('database service error', err);

          res.apiResponse({
            destination: item,
            hotels: hotels
          });
        });
    });
}

I would anyway expect that populate work, just to mantain data the way they are ('destination' should be a model with a 'hotels' array field).

Thanks for any suggestion!
F.

Create thanks work fine :-)
I use it with Keystone 4.0

Why do you import async ?

async is not require after nodeJS v7.6 :)

what does keystone.middleware.api do?