express-apis

Deprecated

This module has renamed to dynapi, no longer maintained.

express-apis

Express dynamic api rendering middleware for more comfortable experience

* This package is not fully completed. If you have any suggestion, welcome to make issues for me ฅ' ω 'ฅ

Introduction

Express-apis is a powerful devtool for building an Express project quickly.

In default, express-apis watches all files in your api directory and mounts them under /api path. When you modify your file, express-apis will re-render the file and you would not have to restart your server again and again.

Quick start

Install the package

$ yarn add express-apis

Use express-apis in your app

import express from 'express'
import apis from 'express-apis'
 
const app = express()
app.use(apis())

Write you APIs like a boss!

// example API routes
project/
|- api/
|  |- middleware.js          // global middleware
|  |- get.js                 // GET: /api
|  |- post.js                // POST: /api
|  |- all.js                 // All methods: /api
|  |- user/_id/
|  |  |- middleware.js       // middleware used to /api/user/:id
|  |  |- param.js            // import User from '~controller/user-model' and checks user id exists or not
|  |  |- put.js              // PUT: /api/user/:id
|  |  |- delete.js           // DELETE: /api/user/:id
|  |  '- getProfile.js       // GET: /api/user/:id/profile
|  |- getUsers.js            // GET: /api/users
|  |- reportSystem_level.js  // REPORT: /api/system/:level
|  '- move_from_to.js        // MOVE: /api/:from/:to
'- controller/               // alias to '~controller'
   '- user-model.js          // import User from '~controller/user-model'

Feature

• ES6/ES2015 syntax supported
• Fully customizable options
• Rich route patterns to keep api folder clean
• Customizable allowed methods and matching order
• Auto rejects request with timeout if middlewares spend too much time
• Build once and rebuild on file changed keeps performance good
• (Coming soon) Customize 404 response when no routes matched
• (Coming soon) Customize 403 response when calling next(Error) in middlewares
• (Coming soon) Add new file type error to allow users handle errors them self

Route file patterns

In default, you can use both simple patterns and complex patterns at the same time.

Simple patterns only contains three types of filename and two types of dirname:

Dirnames

• (Starts without '_') - regular route

Express - Basic routing

The route name will be the kebab-case of the directory name.

Example: dirName(recommend), dir-name, and dir_name will be treated as same as /dir-name.

• (Starts with '_') - param route

Express - Route parameters

The param name will be the snake_case of the directory name.

Example: _param_name(recommand), _paramName, and _param-name will be the same.

Filenames

• middleware.js - middleware file

The middleware file can exists in any path, every param file and method file in the same or sub directories will always pass through the middleware file.

The middleware file file should always export a default function and contains three parameters like (req, res, next).

Always call the next() function, althrough headers is sent.

You can also provide a argument (expect an Error object) to reject the request, it will send a 403 status and { message: err.message } as response.

Express - Writing middleware

• param.js - param file

It's similar to middleware, but you should always provide four parameters like (req, res, next, param).

The param.js file should always be the direct child of param route like user/_id/param.js, and the forth argument will be req.params['id'].

Express - Route parameters

• [METHOD].js - method file

The [METHOD] can be anything in the options.allowedMethods array.

If the [METHOD] is not in options.allowMethods, you'll get an warning and the method file will be ignored.

All the [METHOD] of an method files should always in all lowercase. If the [METHOD] has a '-', ignore '-' and still keep all lowercase.

Express - Method

Complex patterns

• TODO

API

TODO

import { Apis } from 'express-apis'
 
const apis = new Apis({ /* options */ })
// TODO
 
app.use(apis.render)

Options

import { Apis } from 'express-apis'
 
const apis = new Apis({
  rootDir: String, /* Default: process.cwd()
    The project root.
    `apiDir` and `controllerDir` is relative to this option */
 
  apiDir: String, /* Default: 'api'
    The API directory relative to `rootDir`. */
 
  controllerDir: String, /* Default: 'controller'
    The controller directory relative to `rootDir`.
    It will be resolved as `~controller` which imports by files in `apiDir` */
 
  apiRoot: String, /* Default: '/api'
    The API mounting point to the application. */
 
  dev: Boolean, /* Default: true
    Enable dev-mode or not.
    This option has no actual effect now.
    Prepare to used to generate static route files in production mode */
 
  timeout: Number, /* Default: 800
    If middleware doesn't call next(), reject the request after `timeout`ms.
    If timeout === 0, reject any request immediately.
    If timeout < 0, waits the middleware forever until next() has been called */
 
  allowedMethods: [String] /* Default: See below
    Enabled methods of request. */
})

Methods provided by express

ES2015 Syntax Support

Express-apis using babel-core to compile files, preset es2015 and stage-2, plugin async-to-generator and transform-runtime are in used.