Home

Awesome

CircleCI

data-driven extendable API middleware for Node.js/Express

Expressa makes it easy to create basic APIs by using JSON schema:

Best of all: it's just middleware, not a framework


Getting Started

It's very easy to install expressa in your project directory:

mkdir myapp
cd myapp
npm init
npm install expressa express

Create a file app.js with the following code (or just copy the middle 3 lines into your existing express app)

var express = require('express');
var app = express();

var expressa = require('expressa');
app.use('/admin', expressa.admin({ apiurl: '/api/' }));
app.use('/api', expressa.api());

app.listen(3000, function () {
  console.log('Example app listening on port 3000!');
});

Now start the server by running node --use-strict app.js and navigate your browser to http://localhost:3000/admin/

API endpoints

Once you add a collections in the admin interface, every collection will have the following endpoints:

methodendpointdescription
POST/users/loginexpects JSON in the message body. e.g. `{"email": "email@example.com", password: "<the password>"}
GET/:collectionget an array of all documents in a collection
GET/:collection/:idget a specific document
GET/:collection/?query={..}get an array of documents matching the mongo query
GET/:collection/?query={..}&limit=10&offset=10&orderby={"meta.created":1}same as previous, but with targeted output control and sorting
GET/:collection/?query={..}&page=1&pageitems=10similar to previous, but with pagination support
GET/:collection/?query={..}&page=1&pageitems=10&pagemetadisable=1same as previous but slightly faster and with less pagination detail
GET/:collection/?query={..}&fields={..}the fields param can be used to do a mongo projection to request only specific fields
GET/:collection/?fieldname=valueget an array of documents matching with the specified values. See node-mongo-querystring for details.
GET/:collection/schemaget the collection schema
POST/:collection/create a new document, the message body should be the JSON document
PUT/:collection/:idreplace the document with id. The message body should be the JSON document. If the _id in document is different (the old document _id is deleted and a new one with id is created.)
POST/:collection/:id/updatemodify the document with id using a mongo update query. The message body should be the update query
DELETE/:collection/:iddelete the document

Supported Data: Only standard JSON (strings, numbers, booleans, null) is supported. Dates can be stored as strings using ISO 8601

Documentation

Folder Structure

The Expressa configuration is in a folder called "data" in your project. There is a subfolder for the collections that you choose to persist to disk. By default, the following will be added once you finish the installation.

folderpurpose
data/settingsConfig file per environment. Can include custom variables specific to your project.
data/roleList of roles in the permission system. Defaults to "Admin", "Anonymous" and "Authenticated".
data/collectionJSON Schemas and settings for each collection.

Note: The files in these data folders are JSON so they can be manually updated or you can edit them in the Admin UI. Generally these files should be checked into version control.

Admin UI Examples/Screenshots

Expressa ecosystem

Roadmap

Alternatives

Expressa is not primarily built for simple blog websites or mostly static content websites. For those a cms like Keystone.js and enduro.js could work or maybe you could build you site with a static site generator like Hugo. For database-driven websites that need a strong CRUD backend where you want a clear separation between the frontend and backend, expressa.js is a great choice.

Changelog

VersionImportant Changes
0.5.3Fixes bug in install where enforce permissions wasn't activated. Fixes CSV download.
0.5.2Fixes bug when installing super user in Admin tool
0.5.1Includes built Admin UI in npm package
0.5.0Migrates server to use async/await. New Admin UI built with Vue.js. Adds request-id headers
0.4.6Fix some errors in the install process when choosing to store users in mongo or postgres
0.4.5Security update
0.4.1db.create (postgres) now returns the id instead of the full document.
0.4.0Pagination now starts with page 1. Delete requests can no longer bypass rejections by listeners. Updated permission error codes/messages. Error responses now always json (with an "error" field explaining) PUT /collection/:id response changed to match POST /collection
0.3.3Fixes security vulnerability with the "edit own" permission and the :collection/:id/update endpoint. Update immediately.
0.3.2Pagination is now supported by specifying the "page" and "limit"
0.3.1Makes "development" the default settings file instead of "production". Use NODE_ENV environmental variable to change this. To quickly migrate, just rename your settings file to "development".

Inspired by