gossip-api v0.0.5
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
10 years ago