Express-apis NPM

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