Yosemite

Yosemite helps you develop Node-based RESTful web services.

Features

• compatible with Connect
• automatic API doc generation (Swagger spec (v1.2))

Install

npm install yosemite

Getting started

A simple example code.

var yosemite = require('yosemite'),
    connect = require('connect'),
    http = require('http');

var app = yosemite()
    .get('/', function(req, res) {
        res.end('hello, world');
    })
    .get('/ping', function(req, res) {
        res.end('pong');
    });

app.group('/orders')
    .get('/{orderId:int}', function(req, res, orderId) {
        res.end('order: ' + orderId);
    })
    .post('/', function(req, res) {
        res.end('adding new order!');
    });

http.createServer(connect().use('/api', app)).listen(3000);

The code above does the following things.

• It first creates a Yosemite app app.
• Then it registers 2 methods: GET / and GET /ping.
• It also creates a new Group, /orders.
• Then 2 methods GET /{orderId} and POST / are registered to /orders group.
• Lastly, it creates a connect middleware container, registers some middleware and the Yosemite app itself, and starts a HTTP server.

When you run this code, the following paths become available.

• GET /api: will return hello, world
• GET /api/ping: will return pong
• GET /api/orders/1234: will return order: 1234
• POST /api/orders: will return adding new order!
• GET /api/api-docs: will return Swagger 1.2 resource listing JSON
• GET /api/api-docs/orders: will return Swagger 1.2 API declaration JSON for /orders resource

Yosemite app, options, and groups

You can create a Yosemite app with some options.

var app = yosemite({ debug: false, swagger: false });

This is the default options that Yosemite instance will be using by default.

{
    "models": {},

    "swagger": {
        "apiVersion": "1.0",
        "swaggerVersion": "1.2",
        "docPath": "/api-docs",

        "info": {
            "title": "API",
            "description": "",
            "termsOfServiceUrl": "",
            "contact": "",
            "license": "",
            "licenseUrl": ""
        },

        "produces": [ "application/json" ],
        "consumes": [ "application/json" ],

        "debug": true
    },

    "debug": true
}

You can override some options like this:

var opts = {
  swagger: { info: 'My API', description: 'This is my API' }, debug: false }
};

var app = yosemite(opts);

In this case, all other options you didn't specify explicitly (like swagger.docPath or swagger.info.contact) will be the default values.

Yosemite app as Connect middleware

A Yosemite app is a fully compatible Connect middleware. You can register it using Connect#use() function.

In the first example code above, it was registered with /api path prefix, and, that makes all paths specified/used in Yosemite become relative to /api.

Path rules

When you register methods, you can use variable names as part of the path like this:

app.get('/stores/{storeId:int}', function(req, res, storeId) {});
app.delete('/orders/{orderCode:str}', function(req, res, orderCode) {});
app.get('/regions/{regionCode}/accounts/{accountId}', function(req, res, regionCode, accountId) {});

If you specify types {name:type}, passed parameter value in the callback will be in that type.

Groups

You can create topics with Yosemite#group() function. You can group a set of APIs into groups. They will be shown in the same group in API documentation, will share some features or options. Also, if you register methods to the group, their paths will be relative to the base path of the group.

API documentation

By default, all methods registered with the Groups will be shown in auto-generated API docs. But, you can still determine which groups or methods will be shown in the auto-gen docs. When it generates the API docs, Yosemite tries to infer as many information as possible so you can write less code.

References

Yosemite

yosemite([opts])

Creates a Yosemite app. For options, see here.

Yosemite#get(rule, [opts], callback)

Registers a handler callback for GET request that matches rule. You can also provide some options.

• type: data type of this method; normally you specified the name of Model.
• params: additional info for path parameters
• queryParams, headerParams: info for query and header parameters
• body: info for value passed in request BODY
• summary
• notes
• produces
• consumes
• errors

Example

app.get('/order/{orderId:int}', {
        summary: 'Find purchase order by ID',
        desc: 'For valid response try integer IDs with value <= 5. Anything above 5 or non-integers will generate API errors',
        nickname: 'getOrderById',
        params: {
            orderId: { type: 'int', desc: 'test description' }
        },
        type: 'Order',
        errors: {
            400: 'invalid order id',
            404: 'order not found'
        }
    }, function(orderId) {
        this.res.end('order: ' + orderId);
    })

Yosemite#put(), Yosemite#post(), Yosemite#delete()

The same as Yosemite#get() except for the actual HTTP methods: PUT, POST, and DELETE.

Yosemite#group(basePath, options)

Creates a new Group.

Group

Group#get(), Group#put(), Group#post(), Group#delete()

The same as Yosemite#get() but their path rule is relative to the base path of the group.

Data types

You can use the following data type names in rule specifier or inside the Model definition.

• int/int64/long: 64 bit integer
• int32: 32 bit integer
• str/string: string
• bool/boolean: boolean
• float: single point float
• double: double point float
• datetime, dateTime, time: date and time
• date: date

Models

work in progress

Samples

• hello world
• Pet Store API