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