Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 400,000 packages pre-installed, including yarm with all npm packages installed. Try it out:

var yarm = require("yarm")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

yarm v0.4.0

Yet Another REST Middleware for express and mongoose

yarm

Yet Another REST Middleware for node.js, Express and mongoose.

Master branch: Build Status

Development branch: Build Status

Installation

Use npm to install yarm, or add yarm to your package.json dependencies.

$ npm install yarm

yarm has no dependencies, however it is intended to be used with Express and will have additional features if mongoose is present.

Usage

Below is a short introduction to yarm usage, see the complete documentation for more information.

Basics

Use yarm as any other Express middleware.

var app = require("express")();
var yarm = require("yarm");

app.use("/rest", yarm());
app.listen(80);

Serving native javascript resources

Use yarm.native() to serve native Javascript objects or arrays.

var app = require("express")();
var yarm = require("yarm");

app.use("/rest", yarm());

yarm.native("me", {
  name: "Alice",
  age: 30
});

yarm.native("friends", [
  "Bob",
  "Charlie"
]);

app.listen(80);
$ curl http://localhost/rest/me
{
  "name": "Alice",
  "age": 30
}

$ curl http://localhost/rest/me/name
Alice

$ curl http://localhost/rest/friends
{
  "_count": 2,
  "_items": [ "Bob", "Charlie" ]
}

$ curl http://localhost/rest/friends/1
Charlie

Head on to the documentation on Native resources for more details.

Serving mongoose models and aggregates

When mongoose is available, you can use yarm.mongoose() to serve models.

var app = require("express")();
var yarm = require("yarm");
var mongoose = require("mongoose");

app.use("/rest", yarm());

var postSchema = new mongoose.Schema({
  title: String,
  text: String,
  comments: [{
    author: String,
    text: String
  }]
});

var Post = mongoose.model("post", postSchema);

yarm.mongoose("posts", Post);

app.listen(80);
$ curl http://localhost/rest/posts?skip=10&limit=1
{
  "_count": 42,
  "_items": [
    {
      "_id": "507f191e810c19729de860ea",
      "title": "My 11th post",
      "text": "Hello, World",
      "comments": [
        {
          "author": "Bob",
          "text": "First !"
        }
      ]
    }
  ]
}

$ curl http://localhost/rest/posts/507f191e810c19729de860ea
{
  "_id": "507f191e810c19729de860ea",
  "title": "My 11th post",
  "text": "Hello, World",
  "comments": [
    {
      "author": "Bob",
      "text": "First !"
    }
  ]
}

$ curl http://localhost/rest/posts/507f191e810c19729de860ea/comments/0/text
First !

Head on to the documentation on Mongoose resources for more details.

Serving custom resources

Use yarm.resource to define resources with custom handlers.

var app = require("express")(),
var yarm = require("yarm");

yarm.resource("greeting")
  .get(function(req, cb) {
    cb(null, { hello: "world" });
  })
  .sub("french")
    .get(function(req, cb) {
      cb(null, { bonjour: "tout le monde" });
    });

yarm.resource("greeting/pirate")
  .get(function(req, cb) {
    cb(null, { arrrrr: "arrrrrr" });
  });

app.use("/rest", yarm());
app.listen(80);
$ curl http://localhost/rest/greeting
{
  "hello": "world"
}

$ curl http://localhost/rest/greeting/french
{
  "bonjour": "tout le monde"
}

$ curl http://localhost/rest/greeting/pirate
{
  "arrrrr": "arrrrrr"
}

Head on to the documentation on Custom resources for more details.

Extending served resources

yarm allows adding and replacing handlers for any resource or sub-resource. This enables restricting or extending the behaviour of the default native and mongoose resource handlers, as well as defining very complex custom resource hierarchies.


yarm.<whatever>()
  .get(function(req, cb) {
    // Override GET handler here
  });

function notAllowed(req, cb) {
  cb(null, "Nope, sorry :(");
}

yarm.native("readonly", myObject)
  .put(notAllowed)
  .post(notAllowed)
  .del(notAllowed)
    .sub("*")
    .put(notAllowed)
    .post(notAllowed)
    .del(notAllowed);

yarm.resource("already/defined/path")
  .get(function(req, cb) {
    // Will not alter 'already' nor 'already/defined' handlers,
    // nor those for 'already/defined/other' if they are defined
  });

Head on to the documentation on Extending resources for more details.

Contributing

yarm is published under the terms of the MIT license. Feel free to report bugs or send pull requests.

Metadata

RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free