Gossip API

Gossip API is a Node.js module used to create synchronized RESTful Socket-based JSON API services from MongoDB data models. Gossip is based on a combination of technologies that primarily consist of MongoDB, Mongoose, Restify, and Socket.io.

Server Usage

Order of the Day - Get Node.js and MongoDB installed, familiarize yourself with NPM and Mongoose and begin building APIs.

Project

This is pretty much how any Node.js project is setup (note: use "server.js" as your npm entry point).

[~] mkdir myapi && mkdir models && cd myapi
[~/myapi] git init && npm init && npm install mongoose gossip-api

Model(s)

If you are new to the concept of schemas head over to the Mongoose Schema Docs to learn more.

// models/thing.js
module.exports = function(mongoose){
    return mongoose.Schema({
        name   : String,
        gender : String,
        age    : Number,
        __v    : { type: Number, select: false  }
    });
};

Server

Gossip uses Restify to serve up REST services because that is exactly what Restify was designed to do (and it does it really well).

// server.js
var config, modelPath, server;
config = { port: 5000, mongo: 'mongodb://localhost:27017/gossip?w=1' };
modelPath = __dirname + '/models';
server = require('gossip-api')(config, modelPath);
server.listen(config.port, function(){
    console.log('listening on ' + config.port);
});

Note: If you're already familiar with Express then Restify won't be a big jump, check out the Restify Docs to see what I mean.

Run

You just built a synchronized RESTful Socket-based JSON API service on top of MongoDB. Congratulations!

[~/myapi] node server
listening on 5000

RESTful API

The RESTful (Representational State Transfer) API provides a request-response connection between the client and server that allows the client to issue requests as needed. This is most ideal in high latency situations where real-time communications are unnecessary (and probably overkill).

RESTful Routes

These are the routes that you should use whenever possible.

purpose | usage | description --- | --- | --- list | GET /things | Get a list of all documents in the "things" collection create | POST /things | Create a new document in the "things" collection get | GET /things/:id | Get a specific document from the "things" collection update | PUT /things/:id | Update a specific document in the "things" collection delete | DELETE /things/:id | Delete a specific document in the "things" collection

Curl Examples

# GET /things
curl -i -H 'Accept: application/json' http://localhost:5000/things

# POST /things
curl -i -H 'Accept: application/json' -X POST -d 'name=value' http://localhost:5000/things

# GET /things/:id
curl -i -H 'Accept: application/json' http://localhost:5000/things/abcdef0123456789

# PUT /things/:id
curl -i -H 'Accept: application/json' -X PUT -d 'name=value' http://localhost:5000/things/abcdef0123456789

# DELETE /things/:id
curl -i -H 'Accept: application/json' -X DELETE http://localhost:5000/things/abcdef0123456789

Non-RESTful API

If you, for some reason, are unable to use the PUT and DELETE HTTP methods then you may use these non-restful routes as an alternative.

purpose | usage | description --- | --- | --- list | GET /things | Get a list of all documents in the "things" collection create | POST /things | Create a new document in the "things" collection get | GET /things/:id | Get a specific document from the "things" collection update | POST /things/update/:id | Update a specific document in the "things" collection delete | GET /things/delete/:id | Delete a specific document in the "things" collection

Curl Examples

# GET /things
curl -i -H 'Accept: application/json' http://localhost:5000/things

# POST /things
curl -i -H 'Accept: application/json' -X POST -d 'name=value' http://localhost:5000/things

# GET /things/:id
curl -i -H 'Accept: application/json' http://localhost:5000/things/abcdef0123456789

# POST /things/update/:id
curl -i -H 'Accept: application/json' -X POST -d 'name=value' http://localhost:5000/things/update/abcdef0123456789

# GET /things/delete/:id
curl -i -H 'Accept: application/json' http://localhost:5000/things/delete/abcdef0123456789

Socket API

The Socket API provides a persistent connection between the client and server allowing both parties to send data to one another at any time. This is most ideal in low latency situations where real-time communications are a must.

Client Usage

You'll want to swap localhost:5000 with your own server address, but you get the idea.

<script src="http://localhost:5000/socket.io/socket.io.js"></script>
<script src="http://localhost:5000/gossip.js"></script>
<script>
socket.on('connected', function(){
    var things = new model(socket, 'things');
    // do something with your "things" here
});
</script>

Socket Methods

The socket methods mirror the RESTful routes as closely as possible to make going back and forth as seamless as possible.

purpose | usage | description --- | --- | --- list | things.list(callback) | Get a list of all documents in the "things" collection create | things.create(obj, callback) | Create a new document in the "things" collection get | things.get(id, callback) | Get a specific document from the "things" collection update | things.update(doc, callback) | Update a specific document in the "things" collection delete | things.delete(id, callback) | Delete a specific document in the "things" collection on | things.on(state, callback) | Get notified when the state of a document in the "things" collection changes

JavaScript Examples

// list
things.list(function(err, docs){
    // do something
});

// create
things.create({name: value}, function(err, doc){
    // do something
});

// get
things.get('abcdef0123456789', function(err, doc){
    // do something
});

// update
things.update({_id: 'abcdef0123456789', name: value}, function(err, doc){
    // do something
});

// delete
things.delete('abcdef0123456789', function(err){
    // do something
});

// on('created')
things.on('created', function(err, doc){
    // do something
});

// on('updated')
things.on('updated', function(err, doc){
    // do something
});

// on('deleted')
things.on('deleted', function(err, doc){
    // do something
});

License

Licensed under the MIT license