Uberman

A better way to REST

by Elvin Yung

Develop and deploy REST APIs quickly with less boilerplate code.

Introduction

Uberman is an opinionated Node.js HTTPS JSON REST API framework, powered by Express.js and MongoDB.

Quickstart

Install from NPM.

Suppose we want to create a REST API for a blog, which exposes a single endpoint for blog posts. The code to do that is as follows:

var uberman = require('uberman');
var blogAPI = uberman({
    certPath: // PATH TO SSL CERT
    keyPath: // PATH TO SSL KEY
});

blogAPI.addEndpoint('blogPosts', {
    title: String,
    body: String,
    created: {
        type: Date,
        default: Date.now
    },
    upvotes: Number
});

blogAPI.listen();

uberman(config) creates an API and applies the given config. keyCert and keyPath are required fields in the config and must respectively point to an TLS/SSL certificate file and its corresponding private key. Other fields in the config will be discussed later in this readme.

addEndpoint(name, schema[, options]) adds an endpoint in the API with the given schema, and the supplied options. The name is camelized to create the MongoDB collection, and dasherized to create the route. (For example, an endpoint named xTreMeKoolEndPoint would be routed to x-tre-me-kool-end-point, and have a Mongoose model named xTreMeKoolEndPoint.)

In the context of the quickstart example, the route blogPosts was created in the blogAPI, routed to /blog-posts, and backed by a Mongoose model named blogPosts. The following default operations on the endpoint, are also generated:

• a query operation on GET /blog-posts. This is queriable through parameters in the query string.
• a create operation on POST /blog-posts. This accepts only valid JSON with the Content-Type header as application/json.
• a retrieve operation on GET /blog-posts/:id.
• a replace operation on PUT /blog-posts/:id. This accepts only valid JSON with the Content-Type header as application/json.
• an upsert operation on PATCH /blog-posts/:id. This accepts only valid JSON with the Content-Type header as application/json.
• a destroy operation on DELETE /blog-posts/:id

These operations are compliant with RFC 2616 and RFC 5789.

listen([port], [host]) binds connections in the given host and port to the API. By default, Uberman APIs listen on localhost port 443, and accepts only HTTPS connections.

Resources

When you build an endpoint using addEndpoint(name, schema[, options]), you provide a schema, which is the structure of the endpoint's resource, outlined in terms of the fields that the resource contains. Uberman exposes field types through the uberman.Types object, which is essentially a layer on top of the Mongoose Schema.Types. The following types are supported:

String

Number

Date

Buffer

Boolean

Mixed

foreignKey

arrays

nested data

Below is an example schema.

{
    name: String,
    score: Number,
    birthday: Date,

}

Routing

Uberman dasherizes all endpoint routes, and places them under the API root.

The API root is by default set to /api/v{version}, where {version} is the API version set in the config, which is 0 by default. You can change it using the root config field, or the version field if you just want to change the version.

Requests and Responses

By default, Uberman accepts only JSON request bodies (with the Content-Type header as application/json), and returns JSON response bodies. In all cases, the body of the response is unenveloped, and the resource or collection serialized is the entire response body. Any metadata is put in headers.

Uberman uses HATEOAS in its responses. For Uberman, this means that in response bodies, all foreign keys are represented as hyperlinks to the resource referred to.