Quick guide

Let's create REST API on createRest and koa2.

Create app package

mkdir restapi
cd restapi
npm init --force

Install koa2, createrest and createrest-koa

npm install --save koa@2 createrest createrest-koa

Create common files

mkdir src

touch src/app.js
touch src/routes.js

Open app.js and routes.js in IDE/editor.

src/routes.js

// Import createRest function
const { createRest } = require('createrest')
// Here you can import all of your route handlers

// Let's create index and ping-pong handlers
const ping = (ctx) => {
  ctx.body = 'pong'
}

const index = (ctx) => {
  ctx.body = 'Hello world'
}

// Now create routes for your handlers with createRest function
const routes = createRest((root) => {
  // root is a instance of Maker class
  // with root you can define your routes, scopes, hooks

  // Let's create hanler for `GET /` http request
  root.get('/', index) // Complete! .get creates handler

  // Now create handler for `GET /ping`
  root.get('/ping', ping)
})

// Okay, export routes to use in app.js
module.exports = routes

src/app.js

// Import only most necessary dependencies
const Koa = require('koa')
const { createRest, printRoutes } = require('createrest')
const { createKoaRouter } = require('createrest-koa')

// Import our routes
const routes = require('./routes')


// Create simple Koa2 application instance
const app = new Koa()

// Now create router special for koa2
const router = createKoaRouter(routes)

// Here just pass routes to application instance
app.use(router.routes())

// You can change port to listen
app.listen(3000, () => {
  // after app created print available routes to console
  printRoutes(routes)
  console.log('Listening port 3000...')
})

Run your application

node ./src/app.js

You can add npm-script start with node src/app or use nodemon in dev task.

You should see in your console:

GET / -> index()
GET /ping/ -> ping()
Listening port 3000...

And if you open http://localhost:3000/ and http://localhost:3000/ping, you see answers from your index and ping handlers.

Installation

NPM packages

createrest

npm install --save createrest

Import functions

If you use babel or latest build of node.js:

import { createRest, flattenRoutes, printRoutes } from 'createrest'

For commonjs based modules:

const { createRest, flattenRoutes, printRoutes } = require('createrest')

Express

createrest-express

npm install --save createrest createrest-express express

const Express = require('express')
const { createExpressMiddleware } = require('createrest-express')
const routes = require('./routes')

const app = Express()

app.use(createExpressMiddleware(routes))

app.listen(8000)

Koa2

createrest-koa

npm install --save createrest createrest-koa koa@2

const Express = require('koa')
const { createKoaRouter } = require('createrest-express')
const routes = require('./routes')

const app = new Koa()
const router = createKoaRouter(routes)

app.use(router.routes(), router.allowedMethods())

app.listen(8000)

Express example

Installation

npm install express createrest createrest-express

Installation manual for Express here

Source code

// routes.js
const { createRest } = require('createrest')


module.exports.routes = createRest(root => {
  root.beforeEach(beforeEachRequest)

  root.get('/', handleIndexRequest)

  root.scope('scoped', scoped => {
    scoped.get('/example', handleScopedRequest)
  })
})

function beforeEachRequest(req, res, next) {
  console.log('Request')
  next()
}

function handleIndexRequest(req, res) {
  console.log('Handled GET /')
  res.send('Hello!').status(200)
}

function handleScopedRequest(req, res) {
  console.log('Handled GET /scoped/example')
  res.send('That\'s scoped example')
}

// app.js
const Express = require('express')
const { printRoutes } = require('createrest')
const { createExpressMiddleware } = require('createrest-express')

const { routes } = require('./routes')

const PORT = 8000
const app = Express()

app.use(createExpressMiddleware(routes))

app.listen(PORT, () => {
  printRoutes(routes)
  console.log(`Listening port ${PORT}...`)
})

koa example

Installation

npm install koa createrest createrest-koa

Source code

// routes.js
const { createRest } = require('createrest')


module.exports.routes = createRest(root => {
  root.beforeEach(beforeEachRequest)

  root.get('/', handleIndexRequest)

  root.scope('scoped', scoped => {
    scoped.get('/example', handleScopedRequest)
  })
})

function beforeEachRequest(ctx, next) {
  console.log('Request')
  next()
}

function handleIndexRequest(ctx) {
  console.log('Handled GET /')
  ctx.body = 'Hello!'
  ctx.status = 200
}

function handleScopedRequest(ctx) {
  console.log('Handled GET /scoped/example')
  ctx.body = 'That\'s scoped example''
}

// app.js
const Express = require('express')
const { printRoutes } = require('createrest')
const { createKoaRouter } = require('createrest-koa')

const { routes } = require('./routes')

const PORT = 8000
const app = Express()
const router = createKoaRouter(routes)

app.use(router.routes(), router.allowedMethods())

app.listen(PORT, () => {
  printRoutes(routes)
  console.log(`Listening port ${PORT}...`)
})

Handlers

get

Add handler for GET route.

createRest(root => {
  root.get('/', () => console.log('Handle GET /'))

  root.scope('demo', demo => {
    demo.get('/', () => console.log('Handle GET /demo'))
  })
})