PROPUESTAS DE TRABAJO Y MEJORA PARA EL CENTRO EDUCATIVO

RESTful API1 _{became popular because of the demand in distributed systems in which each transaction needs to} include enough information about the state of the client. In a sense, this standard is stateless, because no information about the clients’ states is stored on the server, making it possible for each request to be served by a different system.

Distinct characteristics of RESTful API (i.e., if API is RESTful, it usually follows these principles) are as follows: RESTful API has better scalability support because different components can be deployed

•

independently to different servers.

It replaced the Simple Object Access Protocol (SOAP

• 2_{) because of the simpler verb and noun}

structure.

It uses HTTP methods such as GET, POST, DELETE, PUT, OPTIONS, and so forth. •

JSON is not the only option (although it is the most popular). Unlike SOAP, which is a protocol, •

the REST methodology is flexible in choosing formats. For example alternative formats might be Extensible Markup Language (XML) or comma-separated values formats (CSV).

In Table 8-1 is an example of a simple create, read, update and delete (CRUD3_{) REST API for message collection.}

Table 8-1. Example of the CRUD REST API Structure

Method

URL

Meaning

GET /messages.json Return list of messages in JSON format

PUT /messages.json Update/replace all messages and return status/error in JSON

POST /messages.json Create a new message and return its ID in JSON format

GET /messages/{id}.json Return message with ID {id} in JSON format

PUT /messages/{id}.json Update/replace message with id {id}; if {id} message doesn’t exist, create it DELETE /messages/{id}.json Delete message with ID {id}, return status/error in JSON format

1_{http://en.wikipedia.org/wiki/Representational_state_transfer#Applied_to_web_services.} 2_{http://en.wikipedia.org/wiki/SOAP.}

175

REST is not a protocol; it’s an architecture in the sense that it’s more flexible than SOAP, which we know is a protocol. Therefore, REST API URLs could look like /messages/list.html or /messages/list.xml, in case we want to support these formats.

PUT and DELETE are idempotent methods,4 _{which means that if the server receives two or more similar requests,} the end result is the same.

GET is nullipotent; POST is not idempotent and might affect the state and cause side effects.

More information on REST API5 _{can be found at Wikipedia and in the article “A Brief Introduction to REST} (http://www.infoq.com/articles/rest-introduction).”

In our REST API server, we perform CRUD operations and harness the Express.js middleware

(http://expressjs.com/api.html#middleware) concept with the app.param() and app.use() methods. So, our app should be able to process the following commands using the JSON format (collectionName is the name of the collection, typically pluralized nouns, e.g., messages, comments, users):

• POST /collections/{collectionName}: request to create an object; responds with the of newly created object ID

• GET /collections/{collectionName}/{id}: request with ID to retrieve an object • GET /collections/{collectionName}/: request to retrieve any items from the collection

(items); in our example we’ll have this query options: up to 10 items and sorted by ID • PUT /collections/{collectionName}/{id}: request with ID to update an object • DELETE /collections/{collectionName}/{id}: request with ID to remove an object

Project Dependencies

To get started with our project, we need to install packages. In this chapter, we use Mongoskin

(https://github.com/kissjs/node-mongoskin), a MongoDB library, which is a better alternative to the plain, good-ol’ native MongoDB driver for Node.js (https://github.com/mongodb/node-mongodb-native). In addition, Mongoskin is more lightweight than Mongoose and it is schemaless. For more insights on the library, please check out this Mongoskin comparison blurb, https://github.com/kissjs/node-mongoskin#comparation.

Express.js (http://expressjs.com/) is a wrapper for core Node.js http module (http://nodejs.org/api/http.html) objects. The Express.js framework is built on top of the Connect (https://github.com/senchalabs/connect) middleware library and it provides myriads of convenience. Some people compare the Express.js framework with Ruby’s Sinatra because it’s non-opinionated and configurable.

First, we need to create a ch8/rest-express folder (or download the source code):

$ mkdir rest-express $ cd rest-express

As mentioned in the previous chapter, Node.js/NPM provides multiple ways to install dependencies, including the following:

Manually, one by one •

As a part of

• package.json

By downloading and copying modules •

4_{http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Idempotent_methods_and_web_application.} 5_{http://en.wikipedia.org/wiki/Representational_state_transfer.}

176

To keep things simple, let’s just use the package.json approach. You can create the package.json file, or copy the

dependencies section or the whole file:

{

"name": "rest-express", "version": "0.0.1",

"description": "REST API application with Express, Mongoskin, MongoDB, Mocha and Superagent", "main": "index.js",

"directories": { "test": "test" },

"scripts": {

"test": "mocha test -R spec" },

"author": "Azat Mardan", "license": "BSD", "dependencies": { "express": "4.1.2", "mongoskin": "1.4.1", "body-parser": "1.0.2", "morgan": "1.0.1" }, "devDependencies": { "mocha": "1.16.2", "superagent": "0.15.7", "expect.js": "0.2.0" } }

Then, simply run this command to install modules for the application:

$ npm install

As a result, the node_modules folder should be created with the superagent, express, mongoskin, and expect

libraries. If you change the versions specified in package.json to the later ones, please make sure to update the code according to the packages’ change logs.