Now that our node.js web server
... let's start interacting with it on a more professional basis.
Time to implement an API, aka Application Programming Interface.
Together with other interesting little titbits, this leads to the following topics:
One colleague asked my other colleague Philippe:
Question: In some of your code, you declare a var _self and assign this to it, e.g.:
var _self = this;
_self.load = function () {
Is there any particular reason for that?
Answer: Using _self instead of this is a recommended practice and may help avoid using this in the wrong context, for example when writing code inside a callback.
In that case, this will be pointing to something different than outside.
Check out the Airbnb JavaScript Style Guide, "a mostly reasonable approach to JavaScript".
Back to my issue at hand, talking and interacting sensible and professionally with my web server.
A suitable way to discuss things like that with a web server is by using a REST API, a form of representational state transfer.
To cite Wikipedia, "REST is a software architecture style consisting of guidelines and best practices for creating scalable web services ... that can lead to a more performant and maintainable architecture... RESTful systems typically ... communicate ... with the same HTTP verbs (GET, POST, PUT, DELETE, etc.) used by web browsers to retrieve web pages and send data to remote servers."
One important aspect of the RESTful architecture is the fact that it is stateless.
As an interesting consequence, the REST API PUT and DELETE methods are referred to as idempotent, meaning that the operation will produce the same result no matter how many times it is repeated. The GET method is a safe method (or nullipotent), meaning that calling it produces no side effects.
OK, that's enough theory for today.
Let's dive straight into how to do it instead.
How do we go about implementing a REST API for a node server?
There are a bunch of Node REST API frameworks around to generate this for you automatically.
Nothing goes over learning by doing, though, so let's attack this by hand to start with.
It is simple!
So simple.
And simple is sweet!
I want to add an API to my existing WebGL node server.
The existing implementation code looks like this:
var express = require('express');
var app = express();
app.set('port', (process.env.PORT || 5000));
app.use(express.static(__dirname + '/public'));
app.get('/', function(request, response) {
response.send('Hello World!');
});
app.listen(app.get('port'), function() {
console.log("Node WebGL app is running at localhost:"
+ app.get('port'));
});
I want to avoid disrupting existing clients, of course.
The existing clients just access the base URL of the service, i.e. '/', and the node server returns a static public/index.html.
The response.send('Hello World!') is actually ignored.
I also want to avoid disrupting future clients if the API ever changes, so I define a version number v1 for the API I implement now and add modify my node server implementation like this:
var express = require('express');
var app = express();
var api = require('./routes/api');
app.set('port', (process.env.PORT || 5000));
app.use(express.static(__dirname + '/public'));
app.get('/', function(req, res) {}); // leads to public/index.html
app.get('/api/v1', api.v1);
app.listen(app.get('port'), function() {
console.log("Node WebGL app is running at localhost:"
+ app.get('port'));
});
Just like before, it will respond to a call to the base URL by serving up public/index.html.
A call to the base URL with an appended path '/api/v1' will access the first version of my new API, which is implemented like this in a new module named routes/api.js:
exports.v1 = function(req, res) {
res.send('v1: Hello World!');
};
This implementation is up and running live already at the same Herouku URL as before, nameless-harbor-7576.herokuapp.com, and can be embedded right here:
The complete updated source code is stored in the NodeWebGL GitHub repository, and the version discussed here is release 1.0.0.2.
For now, the API does nothing useful whatsoever, but I'll get to that next :-)
I you are hungry for a more complete real-life sample right here and now, you can take a look at Cyrille Fauvel's Node.js View and Data API sample, e.g. start.js.