A step-by-step guide for development of Node.js APIs

Many articles describe the interaction between Node.js and Elasticsearch, but they often do not clearly explain how this interaction was achieved. To fill this gap, this article describes test-driven, step-by-step development of a simple RESTful API into an Elasticsearch in Node.js.

My main intention is to show Node.js developers how a RESTful API might be written using a TDD approach. Applying TDD practices makes the process much faster and results in a less error-prone API. Moreover, the whole application architecture becomes testable and therefore simpler and cleaner.

This article is divided into three main sections, with subsections and numbered steps to facilitate ease of use:

The

Proposed Architecture

section covers setup, installing the test framework, creating the first test, and defining the server.

The

Develop and Test Server

section describes preparing the server for content testing, as well as testing and adding support to the server.

The

Develop and Test Controller

section provides detail on developing the initial controller so that it supports standard REST actions (index, show, update, and destroy), and on refactoring the controller after this development.

Proposed Architecture

Let's start with the general API architecture. Some elements of MVC patterns can be successfully reused here. Strictly speaking, I am going to focus primarily on one element of that pattern: the Controller. The architecture I am going to develop is represented by the gray rectangle in the schema below:

Set Up Architecture

1. Create an application directory:

bash

1mkdir npm_api
2cd npm_api

2. Initialize the git repository:

git init

3. Initialize the npm application:

npm init

4. Accept all proposed default values.

Install Test Framework, Create First Test, Define Server

Mocha

’s

framework will work well for this project.

1. Install Mocha:

npm install --save-dev mocha

2. Create an empty directory for tests:

mkdir test

3. Configure Mocha as your default test framework in the package.json:

text

1"scripts": {
2  "test": "node_modules/.bin/mocha"
3}

The above steps enable you to run tests with the default npm command:

npm test

At this point, you should see something like

No test files found

in the output. This is expected. We have not created any tests so far. That is the next step.

4. Install the supertest library for request testing:

npm install --save-dev supertest

5. Create the first test:

test/server.js:

javascript

1describe('server', () => {
2  const request = supertest(server);
3
4  //checks that server returns success response when 'GET /posts' is performed
5  //response content is not verified here yet. It will be done in the next
6  //iteration 
7  describe('GET /posts', () =>
8    it('responds with OK', () =>
9      request
10        .get('/posts')
11        .expect(200)
12    )
13  );
14});

6. Run the first test and see this expected error message:

Error: Cannot find module '../app/server'

7. Configure server instance:

I will use the Restify package for building the web API:

npm install --save-dev restify

Here is the basic trivial server just to make our only test green:

javascript

1const restify = require('restify');
2const server = restify.createServer();
3
4//Server always responds with the empty object for now. Content 
5//is not tested yet. Just server availability is tested. 
6server.get('/posts', (req, res, next) =>
7  res.send({})
8);
9
10module.exports = server;

You can see that this is a very trivial server definition. It has only one action defined,

GET /posts

, which always returns an empty object. If all steps have been done properly, then

npm test

will output:

text

1server
2  GET /posts
3    ✓ responds with OK
4
51 passing (32ms)

Now we have a server that responds to

GET /posts

properly. It is the perfect time to make our first manual integration test to check that all the pieces we have created fit together properly.

8. Create script that runs the server:

./start.js:

javascript

1const server = require('./app/server');
2
3server.listen(8080, () =>
4  console.log('%s listening at %s', server.name, server.url)
5);

9. Update package.json to define it as an application start script:

package.json:

text

1"script": {
2  "test": "node_modules/.bin/mocha",
3  "start": "node start.js"
4}

10. Run the server itself:

npm start

The server should be running and ready to accept requests on the port 8080:

text

1> node_api@1.0.0 start /projects/node_api
2> node start.js
3
4restify listening at https://[::]:8080

It will always respond with an empty object as expected:

curl -XGET https://localhost:8080/posts {}%

Now we have an API server that is ready to respond to our requests.

Develop and Test Server

According to our proposed architecture, the server should redirect all requests to the controller,

PostsController

in our case. It will be responsible for handling requests, gathering all necessary data, and rendering results.

Prepare Server for Content Testing

1. Extract the controller from the current server implementation:

app/controllers/posts.js:

text

1module.exports = class {
2  index() {
3    //even at this early phase we can assume that controller will return
4    //some kind of promise because it will make a request to ES that 
5    //are asynchronous
6    return new Promise((resolve, reject) =>
7      resolve({})
8    );
9  }
10};

This is the simplest possible controller version.

2. Modify our server to use the controller:

javascript

1const restify = require('restify');
2const server = restify.createServer();
3const PostsController = require('./controllers/posts.js');
4
5const posts = new PostsController();
6
7server.get('/posts', (req, res, next) =>
8  posts.index().then((result) =>
9    res.send(200, result)
10  )
11);
12
13module.exports = server;

Now we have a controller instance that has been created INSIDE the server. But to be able to write isolated unit tests of the server, we need some way to pass a fake controller to the server and then ensure that all methods on that fake controller are within proper parameters.

3. Modify the server to be able to accept controller instance:

app/server.js:

javascript

1const restify = require('restify');
2
3//PostsController intance must be created and passed from outside
4module.exports = (posts) => {
5  const server = restify.createServer();
6
7  server.get('/posts', (req, res, next) =>
8    posts.index().then((result) =>
9      //we are not testing content here just server availability
10      res.send(200)
11    )
12  );
13
14  return server;
15};

As a result of this step, we have defined the server factory rather than the server definition. This server factory created a server instance based on the controller parameters that it accepts.

Test Server

1. Modify the server test and specify fake controller instance:

test/server.js:

javascript

1const supertest = require('supertest');
2const server = require('../app/server');
3
4describe('server', () => {
5  //PostsController stub
6  const posts = {};
7  const request = supertest(server(posts));
8
9  describe('GET /posts', () => {
10    //test function that is called by the server instance
11    before(() => {
12      posts.index = () =>
13        new Promise((resolve, reject) =>
14          resolve({})
15        );
16    });
17
18    it('responds with OK', () =>
19      request
20        .get('/posts')
21        .expect(200)
22    );
23  });
24});

You can see above that posts is a simple, plain object used as a controller stub object that has only one method,

index

, defined on it. That makes it possible to control both the results that are returned to the server from the controller, and the params that are passed from the server to the controller. (More detail on this below.) If the steps have been done properly, all tests will be green now.

2. Run test:

npm test

3. Modify our start script and pass real PostsController instance to the server instance:

./start.js:

javascript

1const serverFactory = require('./app/server');
2const PostsController = require('./app/controllers/posts');
3
4const posts = new PostsController();
5const server = serverFactory(posts);
6
7server.listen(8080, () =>
8  console.log('%s listening at %s', server.name, server.url)
9);

4. Make a simple integration test to check that nothing is broken:

Run server:

npm start

Send a test request to the server:

curl -XGET https://localhost:8080/posts {}%

An empty object is returned, which is exactly what was expected. Now we have everything prepared for content testing, specifically making sure that the server properly serializes data that is returned from the controller and responds with that data.

5. Update test so it becomes red:

test/server.js:

typescript

1const _ = require('lodash');
2const supertest = require('supertest');
3const server = require('../app/server');
4
5describe('server', () => {
6  const posts = {};
7  const request = supertest(server(posts));
8
9  describe('GET /posts', () => {
10    //test data that is returned by the posts controller stub
11    const data = [{id: 1, author: 'Mr. Smith', content: 'Now GET /posts works'}];
12
13     //test method now returns test data
14    before(() => {
15      posts.index = () =>
16        new Promise((resolve, reject) =>
17          resolve(data)
18        );
19    });
20
21    //checks that server responds with the proper HTTP code and exactly with the     
22    //same data it received from the controller
23    it('responds with OK', () =>
24      request
25        .get('/posts')
26        .expect(data)
27        .expect(200)
28    );
29  });
30});

6. Run npm test and see an error:

Error: expected [ { id: 1, author: 'Mr. Smith', content: 'Now GET /posts works' } ] response body, got {}

It looks like the server does not return post data. The server needs to be modified.

7. Update server:

javascript

1const restify = require('restify');
2
3module.exports = (posts) => {
4  const server = restify.createServer();
5
6  server.get('/posts', (req, res, next) =>
7    posts.index().then((result) =>
8      //now we returns not only code but content also
9      res.send(200, result)
10    )
11  );
12
13  return server;
14};

If you run

npm test

now, you should see that all tests are green. Nice!

Add Support to Create New Post Instance

Now it's time to add support for one more action to our server,

POST /posts

, that will create a new post instance.

1. Create test:

test/server.js:

typescript

1describe('POST /posts', () => {
2  //data that is sent to the server
3  const data = [{ author: 'Mr. Rogers', content: 'Now POST /posts works' }];
4
5  before(() => {
6    //so we expect server to return attributes fo the new post
7    posts.create = (attrs) =>
8      new Promise((resolve, reject) =>
9        resolve(_.merge({ id: 2 }, attrs))
10      );
11  });
12
13  it('responds with Created and returns content of the newly create post', () =>
14    request
15      .post('/posts')
16      .send({ post: data })
17      .expect(_.merge({ id: 2 }, data))
18      .expect(201)
19  );
20});

2. Run npm test and see the following error:

text

1Error: expected { '0': { author: 'Mr. Rogers', content: 'Now POST /posts works' },
2  id: 2 } response body, got { code: 'MethodNotAllowedError',
3  message: 'POST is not allowed' }

This result is actually expected.

POST /posts

must be defined on the server to fix the test.

3. Define POST /posts on the server:

app/server.js:

text

1//So here we just pass post attributes to the controller and returns back 
2//its result
3server.post('/posts', (req, res, next) =>
4  posts.create(req.params.post).then((result) =>
5    res.send(201, result)
6  )
7);

If we run npm test at this point, we will still see an error:

Error: expected { '0': { author: 'Mr. Rogers', content: 'Now POST /posts works' }, id: 2 } response body, got { id: 2 }

It looks like the params we sent to the server were not parsed properly.

4. Plug body parser into the server:

app/server.js:

javascript

1const restify = require('restify');
2
3module.exports = (posts) => {
4  const server = restify.createServer();
5
6  //we need that parser to work with params that are defined in 
7  //the request body
8  server.use(restify.bodyParser());
9
10  server.get('/posts', (req, res, next) =>
11    posts.index().then((result) =>
12      res.send(200, result)
13    )
14  );
15
16  server.post('/posts', (req, res, next) =>
17    posts.create(req.params.post).then((result) =>
18      res.send(201, result)
19    )
20  );
21
22  return server;
23};

5. Run npm test again. Everything should be fine.

The next action I am going to add is

GET /posts/:id

. This action is different from the previous two. It's tricky in that the API consumer might specify nonexistent post identities that the server must handle gracefully. For now, let's implement a simple action version that does not handle situations when posts do not exist.

6. Create test as usual:

test/server.js

typescript

1describe('GET /posts/:id', () => {
2  //data that is returned from the controller stub
3  const data = [{ author: 'Mr. Williams', content: 'Now GET /posts/:id works' }];
4
5  //show action stub. it merges specified id with the predefined data
6  //to imitate real controller behaviour at one hand and
7  //check that proper id was passed to the controller at another one
8  before(() => {
9    posts.show = (id) =>
10      new Promise((resolve, reject) =>
11        resolve(_.merge({ id: id }, data))
12      );
13  });
14
15  //checks that server just pass id to the controller and 
16  //returns its result. 
17  it('responds with OK and returns content of the post', () =>
18    request
19      .get('/posts/3')
20      .send(data)
21      .expect(_.merge({ id: 3 }, data))
22      .expect(200)
23  );
24});

7. Run npm test and get an error:

Error: expected { '0': { author: 'Mr. Williams', content: 'Now GET /posts/:id works' }, id: 3 } response body, got { code: 'ResourceNotFound', message: '/posts/3 does not exist' }

The resource is not found. We need to define the action on the server.

8. Define action on the server:

app/server.js:

text

1server.get('/posts/:id', (req, res, next) =>
2  posts.show(req.params.id).then((result) =>
3    res.send(200, result)
4  )
5);

9. Run test. Now everything should be green!

But what about cases when there is no post with the specified

? The server should obviously return NotFound (404) HTTP status in this case. Let’s continue by addressing this situation.

10. Add test:

test/server.js:

text

1context('when there is no post with the specified id', () => {
2  //here its assumed that controller will return rejected promice
3  //when post with the specified id is not found
4  before(() => {
5    posts.show = (id) =>
6      new Promise((resolve, reject) =>
7        reject(id)
8      );
9  });
10
11  //test that server responds with 404 code if post was not found
12  it('responds with NotFound', () =>
13    request
14      .get('/posts/3')
15      .send(data)
16      .expect(404)
17  );
18});

11. Run npm test again and get an error:

Error: timeout of 2000ms exceeded. Ensure the done() callback is being called in this test.

This error occurred because the promise in the controller stub was rejected. We need to modify the server to handle this circumstance.

12. Correct error:

app/server.js:

text

1server.post('/posts', (req, res, next) =>
2  posts.show(req.params.id).then((result) =>
3    res.send(200, result)
4  ).catch(() => res.send(404))
5);

13: Run tests again. They should all be green.

The next action in line involves update:

POST /posts/:id

. Similar to the previous action, we must develop a clear path first, assuming that the correct post

is specified. We will consider situations when an invalid

is specified later.

14. Create test first as usual:

text

1describe('POST /posts/:id', () => {
2  //data that is sent to the server
3  var data = [{ author: 'Mr. Williams', content: 'Now POST /posts/:id works' }];
4
5  //test actions returns specified attributes merged with the
6  //specified identified so it's possible to control correctness
7  //of the parameters that were passed to the controller stub
8  before(() => {
9    posts.update = (id, attrs) =>
10      new Promise((resolve, reject) =>
11        resolve(_.merge({ id: id }, attrs))
12      );
13  });
14
15  //and in the test below response data and status are verified
16  it('responds with Created and returns content of the updated post', () =>
17    request
18      .post('/posts/4')
19      .send({ post: data })
20      .expect(_.merge({ id: 4 }, data))
21      .expect(200)
22  );
23});

15. Run test and see an expected error:

text

1Error: expected { '0': { author: 'Mr. Williams', content: 'Now POST /posts/:id works' },
2  id: 4 } response body, got { code: 'MethodNotAllowedError',
3  message: 'POST is not allowed' }

16. Define missing method:

app/server.js:

text

1server.post('/posts/:id', (req, res, next) =>
2  posts.update(req.params.id, req.params.post).then((result) =>
3    res.send(200, result)
4  )
5);

Now we have an updated server action that is capable of handling existing resources. It's time to address cases when the identifier of nonexistent posts is specified.

17. Create the test:

test/server.js:

text

1context('when there is no post with the specified id', () => {
2  before(() => {
3    posts.update = (id) =>
4      new Promise((resolve, reject) =>
5        reject(id)
6      );
7  });
8
9  it('responds with 404 HTTP response', () =>
10    request
11      .post('/posts/3')
12      .send({ post: data })
13      .expect(404)
14  );
15});

18. Run npm test and get an error:

Error: timeout of 2000ms exceeded. Ensure the done() callback is being called in this test.

This result is expected. Rejected promises have not been addressed yet.

19. Add error handling to the server action:

text

1server.post('/posts/:id', (req, res, next) =>
2  posts.update(req.params.id, req.params.post).then((result) =>
3    res.send(200, result)
4  ).catch(() => res.send(404))
5);

20. Run tests again. They are green!

At this point, only one action has not been implemented:

DELETE /posts/:id

. Now it's time to fill this gap. Here is the code for the action test:

text

1describe('DELETE /posts/:id', () => {
2  //imitate action that always returns id of the deleted post
3  before(() =>
4    posts.destroy = (id) =>
5      new Promise((resolve, reject) =>
6        resolve({ id: id })
7      )
8  );
9
10  //checks that server returns deleted post identified
11  it('responds with the id of the deleted post', () =>
12    request
13      .delete('/posts/5')
14      .expect({ id: 5 })
15  );
16});

21. Run action test. Get an error.

22. Define action on the server:

text

1server.del('/posts/:id', (req, res, next) =>
2  posts.destroy(req.params.id).then((result) =>
3    res.send(200, { id: req.params.id })
4  )
5);

23. Run tests again. Green!

Now let's handle cases when there is no post with the specified

. Here is the test code: test/server.js:

text

1context('when there is no post with the specified id', () => {
2  before(() =>
3    posts.destroy = (id) =>
4      new Promise((resolve, reject) =>
5        reject(id)
6      )
7  );
8
9  it('responds with NotFound', () =>
10    request
11      .delete('/posts/5')
12      .expect(404)
13  );
14});

24. Run the test. Get timeout error.

25. Update server:

app/server.js:

text

1server.del('/posts/:id', (req, res, next) =>
2  posts.destroy(req.params.id).then((result) =>
3    res.send(200, { id: req.params.id })
4  ).catch(() => res.send(404))
5);

Everything is green. Now we have a fully workable server. It properly redirects request data to the controller and writes serialized results to the response. It does not yet access ES instances and returns dummy data. This function is addressed below.

Develop and Test Controller

This section concerns specifically the

PostsController

. It will work with an ES client. We can assume that the ES client is well-tested so we do not have to test it ourselves. Only the methods of the controller in isolation should be tested. To do so, we need to pass the client stub to the controller instance to be able to verify that the correct methods were called on the stub, and the returned data was properly handled.

Prepare Controller for Testing

1. Update PostsController definition so it accepts client instance from outside:

app/controllers/posts.js:

text

1module.exports = class {
2  constructor(client) {
3    this.client = client;
4  }
5
6  index() {
7     //controller still always returns empty object
8    return new Promise((resolve, reject) =>
9      resolve({})
10    );
11  }
12};

2. Install another test library:

npm install should --save-dev

3. Introduce the ES client stub into the posts controller test:

test/controllers/posts.js:

javascript

1var PostsController = require('../../app/controllers/posts');
2
3describe('PostsController', function() {
4  var client = {};
5  var posts = new PostsController(client);
6});

4. Run tests. Everything should be green.

Now we have prepared the basis for

PostsController

development.

Test Controller

1. Write our first test - index action.

Here is the test code:

text

1describe('index', () => {
2  before(() =>
3    client.search = () =>
4      new Promise((resolve, reject) =>
5        resolve({
6          "took": 27,
7          "timed_out": false,
8          "_shards": {
9            "total": 5,
10            "successful": 5,
11            "failed": 0
12          },
13          "hits": {
14            "total": 1,
15            "max_score": 1,
16            "hits": [
17              {
18                "_index": 'index',
19                "_type": 'type',
20                "_id": "AVhMJLOujQMgnw8euuFI",
21                "_score": 1,
22                "_source": {
23                  "text": "Now PostController index works!",
24                  "author": "Mr.Smith"
25                }
26              }
27            ]
28          }
29        })
30      )
31  );
32
33  it('parses and returns post data', () =>
34    posts.index().then((result) =>
35      result.should.deepEqual([{
36        id: "AVhMJLOujQMgnw8euuFI",
37        author: "Mr.Smith",
38        text: "Now PostController index works!"
39      }])
40    )
41  );
42});

We see that the possible ES response is imitated here.

2. Run the first test and see a failure. Our current PostsController always returns an empty object.

3. Correct failure:

typescript

1const _ = require('lodash');
2
3module.exports = class {
4  constructor(client) {
5    this.client = client;
6  }
7
8  //index returns list of posts attributes merged with corresponding
9  //identifiers
10  index() {
11    return this.client
12      .search()
13      .then((res) =>
14        _.map(res.hits.hits, (hit) =>
15          _.merge(hit._source, { id: hit._id })
16        )
17      );
18  }
19};

4. Run test again. Green!

Test Parameters

We just tested that

PostsController

parsed the ES result properly, but we also need to test that it passes correct params to the client. Two params of the ES client method need to be specified:

search: index

and

type

1. Add params to the PostsController constructor:

app/controllers/posts.js:

text

1//index and type names should be specified outside now
2constructor(client, indexName, type) {
3  this.client = client;
4  this.indexName = indexName;
5  this.type = type;
6}

2. Specify test params in the PostsController specs:

test/controller/posts.js:

javascript

1describe('PostsController', () => {
2  const client = {};
3  //'index' and 'type' are some virtual index and type names 
4  const posts = new PostsController(client, 'index', 'type');
5  ...
6}

3. Run test again. Green! Nothing is broken.

4. Verify that we specified those params properly in test when client.search method is called.

I am going to use

sinon

for spying on method calls:

npm install sinon --save-dev

I am using should-sinon for should - like asserts:

npm install should-sinon --save-dev

Specify these in the controller test: test/controllers/posts.js:

var sinon = require('sinon'); require('should-sinon');

Now we can write a params verification test: test/controllers/posts.js:

javascript

1it('specifies proper index and type while searching', () => {
2  const spy = sinon.spy(client, 'search');
3
4  //It's expected below that method search() is called once with
5  //proper index name and object type as paramters. 
6  return posts.index().then(() => {
7    spy.should.be.calledOnce();
8    spy.should.be.calledWith({
9      index: 'index',
10      type: 'type'
11    });
12  });
13});

5. Run npm test. See the following failure:

text

1expected 'search' to be called with arguments { index: "index", type: "type" }
2    search() => [Promise] {  } at PostsController.index (/projects/node_api/app/controllers/posts.js:14:22)
3    expected false to be true

6. Update the controller:

app/controllers/posts.js:

text

1index() {
2  //pass index name and object type to the controller
3  return this.client.search({
4    index: this.indexName,
5    type: this.type
6  })
7  .then((res) =>
8    _.map(res.hits.hits, (hit) =>
9      _.merge(hit._source, { id: hit._id })
10    )
11  );
12}

The tests should be green.

Create and Run Manual Integration Tests

Now is a good time to run simple manual integration tests to be sure that all the pieces we have created correspond properly. Each piece is covered by its own unit test. We cannot be sure they all interact correctly without integration testing. It would be best to create manual integration tests for this purpose, but that is beyond the scope of this article. To complete the following steps, you should have ES service installed locally and be running on default 9200 port.

1. Create index ( 'node_api' ):

curl -XPOST localhost:9200/node_api

Expected output:

{"acknowledged":true}%

2. Create post example:

curl -XPOST localhost:9200/node_api/posts -d '{ "author": "Mr. Smith", "content": "Now GET /posts works!" }'

Expected output:

{"_index":"node_api","_type":"posts","_id":"AViW9F1lhQ3AxSLOwi2k","_version":1,"created":true}%

3. Install elasticsearch npm package:

npm install elasticsearch --save-dev

4. Create ES client instance:

./app/client.js:

javascript

1const elasticsearch = require('elasticsearch');
2
3module.exports = new elasticsearch.Client({
4  host: 'localhost:9200'
5});

5. Update start script with the real index and type names:

./start.js:

javascript

1const client = require('./app/client');
2const serverFactory = require('./app/server');
3const PostsController = require('./app/controllers/posts');
4
5const posts = new PostsController(client, 'node_api', 'posts');
6const server = serverFactory(posts);
7
8server.listen(8080, () =>
9  console.log('%s listening at %s', server.name, server.url)
10);

6. Run server:

npm start

7. Make test request:

curl -XGET https://localhost:8080/posts/1

If all steps have been done properly, you should see something like this in the output:

[{"author":"Mr. Smith","content":"Now GET /posts works!","id":"AViW9F1lhQ3AxSLOwi2k"}]%

Our integration test was successful. We can continue adding methods to the controller, knowing that the server has been configured properly and calls proper controller methods.

Implement Post Indexing in ES

1. Create test code:

typescript

1describe('create', () => {
2  const attrs = { author: 'Mr. Rogers', text: "Now PostController create works!" };
3
4  before(() => {
5    client.index = () =>
6      new Promise((resolve, reject) =>
7        resolve({
8          "_index": 'index',
9          "_type": "type",
10          "_id": "AViXYdnZxmF-_Ui11JAF",
11          "_version": 1,
12          "created": true
13        })
14      );
15  });
16
17  it('parses and returns post data', () =>
18    posts.create(attrs).then((result) =>
19      result.should.deepEqual(_.merge({ id: "AViXYdnZxmF-_Ui11JAF" }, attrs))
20    )
21  );
22
23  it('specifies proper index, type and body', () => {
24    const spy = sinon.spy(client, 'index');
25
26    return posts.create(attrs).then(() => {
27      spy.should.be.calledOnce();
28      spy.should.be.calledWith({
29        index: 'index',
30        type: 'type',
31        body: attrs
32      });
33    });
34  });
35});

Two tests are defined above. In real situations, these tests would consist of two interactions. I joined them into one interaction here for simplicity’s sake.

2. Run tests and see errors

3. Add indexing support to the controller:

sql

1create(attrs) {
2  return this.client.index({
3    index: this.indexName,
4    type: this.type,
5    body: attrs
6  })
7  .then((res) =>
8    _.merge({ id: res._id }, attrs)
9  );
10}

The tests will be green if steps have been done properly.

Implement “Show” Action

The next controller action is show. Similar to

GET /show/:id

, this controller action should handle situations when a post with a specified identifier does not exist. We will take care of that later. Now, let's start from the simplified action version, assuming that only a correct identifier can be specified.

1. Create test first as usual:

test/controllers/posts.js:

typescript

1describe('show', () => {
2  const id = "AVhMJLOujQMgnw8euuFI";
3  const attrs = [{ author: 'Mr. Williams', content: 'Now PostsController show works!' }];
4
5  before(() =>
6    client.get = () =>
7      new Promise((resolve, reject) =>
8        resolve({
9          "_index": 'index',
10          "_type": 'post',
11          "_id": id,
12          "_version": 1,
13          "found": true,
14          "_source": attrs
15        })
16      )
17  );
18
19  it('parses int returns post data', () =>
20    posts.show(id).then((result) =>
21      result.should.deepEqual(_.merge({ id: id }, attrs))
22    )
23  );
24
25  it('specifies proper index, type and id', () => {
26    const spy = sinon.spy(client, 'get');
27
28    return posts.show(1).then(() => {
29      spy.should.be.calledOnce();
30      spy.should.be.calledWith({
31        index: 'index',
32        type: 'type',
33        id: 1
34      });
35    });
36  });
37});

2. Run npm test, get error.

If you run

npm test

now, you will see an error because method

show

has not been defined on the

PostsController

3. Correct error:

app/controllers/posts.js:

text

1show(id) {
2  return this.client.get({
3    index: this.indexName,
4    type: this.type,
5    id: id
6  })
7  .then((res) =>
8    _.merge({ id: res._id }, res._source)
9  );
10}

4. Run npm test again. All tests should be green.

The

PostsController

is now able to find the post and return its content. But if the identifier of a nonexistent post was specified, the controller will fail. We need to handle this exceptional situation properly.

5. Create test for nonexistent post identifier:

test/controllers/posts.js:

text

1context('when there is no post with the specified id', () => {
2  before(() =>
3    client.get = () => {
4      return new Promise((resolve, reject) =>
5        resolve({
6          "_index": 'index',
7          "_type": 'post',
8          "_id": id,
9          "found": false
10        })
11      );
12    }
13  );
14
15  it('returns rejected promise with the non existing post id', () =>
16    posts.show(id).catch((result) =>
17      result.should.equal(id)
18    )
19  );
20});

6. Run test and get an error.

7. Update controller:

app/controllers/posts.js:

text

1show(id) {
2  return this.client.get({
3    index: this.indexName,
4    type: this.type,
5    id: id
6  })
7  .then((res) =>
8    new Promise((resolve, reject) => {
9      if (res.found) {
10        return resolve(_.merge({ id: res._id }, res._source));
11      }
12
13      reject(id);
14    })
15  );
16}

Now we have fully implemented show action.

Enable “Update” Function

The next action concerns

update

. As in the case of

show

action, we need to address situations when a nonexistent post identifier is passed to the action. Also similar to the

show

, we will handle that later and start from a simplified version.

1. Create the test code:

typescript

1describe('update', () => {
2  const id = "AVhMJLOujQMgnw8euuFI";
3  const attrs = [{ author: 'Mr. Williams', content: 'Now PostsController show works!' }];
4
5  before(() =>
6    client.update = () =>
7      new Promise((resolve, reject) =>
8        resolve({
9          "_index": "index",
10          "_type": "type",
11          "_id": id,
12          "_version": 4
13        })
14      )
15  );
16
17  it('parses and returns post data', () =>
18    posts.update(id, attrs).then((result) =>
19      result.should.deepEqual(_.merge({ id: id }, attrs))
20    )
21  );
22
23  it('specifies proper index, type, id and attrs', () => {
24    const spy = sinon.spy(client, 'update');
25
26    return posts.update(id, attrs).then(() => {
27      spy.should.be.calledOnce();
28      spy.should.be.calledWith({
29        index: 'index',
30        type: 'type',
31        id: id,
32        doc: attrs
33      });
34    });
35  });
36});

2. Run npm test and get these errors:

text

11) PostsController update parses and returns post data:
2   TypeError: posts.update is not a function
3    at Context.it (test/controllers/posts.js:178:13)
4
52) PostsController update specifies proper index, type, id and attrs:
6   TypeError: posts.update is not a function
7    at Context.it (test/controllers/posts.js:186:20)

So,

update

is not yet a function. Let’s fix this.

3. Define update method:

app/controllers/posts.js:

sql

1update(id, attrs) {
2  return this.client.update({
3    index: this.indexName,
4    type: this.type,
5    id: id,
6    doc: attrs
7  })
8  .then((res) =>
9    _.merge({ id: res._id }, attrs)
10  );
11}

The errors should be corrected. Now it's time to address situations when an identifier of a nonexistent resource is specified.

4. Create test for nonexistent ID specification:

text

1context('when there is no post with the specified id', () => {
2  before(() =>
3    client.update = () => {
4      return new Promise((resolve, reject) =>
5        resolve({
6          "error": "DocumentMissingException[[node_api][3] [posts][AVhMJLOujQMgnw8euuFI]: document missing]",
7          "status": 404
8        })
9      );
10    }
11  );
12
13  it('returns rejected promise with the non existing post id', () =>
14    posts.update(id, attrs).catch((result) =>
15      result.should.equal(id)
16    )
17  );
18});

5. Run test and see a failure.

6. Update the definition of the method update:

sql

1update(id, attrs) {
2  return this.client.update({
3    index: this.indexName,
4    type: this.type,
5    id: id,
6    doc: attrs
7  })
8  .then((res) =>
9    new Promise((resolve, reject) => {
10      if (res._id) {
11        return resolve(_.merge({ id: res._id }, attrs));
12      }
13
14      reject(id);
15    })
16  );
17}

7. Run tests. They should be green.

Enable “Destroy” Function

This is the final

REST

action to be implemented. As with previous actions, we need to handle situations when the

of the non-existing resource is specified as a parameter of the action. Also following our previous methods, we will implement a simple action version first and handle non-existing sources second.

1. Create the test code:

test/controllers/posts.js:

typescript

1describe('destroy', () => {
2  const id = "AVhMJLOujQMgnw8euuFI";
3
4  before(() =>
5    client.delete = () =>
6      new Promise((resolve, reject) =>
7        resolve({
8          "found": true,
9          "_index": "index",
10          "_type": "type",
11          "_id": id,
12          "_version": 6
13        })
14      )
15  );
16
17  it('parses and returns post data', () =>
18    posts.destroy(id).then((result) =>
19      result.should.equal(id)
20    )
21  );
22
23  it('specifies proper index, type and id', () => {
24    const spy = sinon.spy(client, 'delete');
25
26    return posts.destroy(id).then(() => {
27      spy.should.be.calledOnce();
28      spy.should.be.calledWith({
29        index: 'index',
30        type: 'type',
31        id: id
32      });
33    });
34  });
35});

2. Run npm test. See these errors:

text

11) PostsController destroy parses and returns post data:
2   TypeError: posts.destroy is not a function
3    at Context.it (test/controllers/posts.js:234:13)
4
52) PostsController destroy specifies proper index, type and id:
6   TypeError: posts.destroy is not a function
7    at Context.it (test/controllers/posts.js:242:20)

3. Define destroy action:

text

1destroy(id) {
2  return this.client.delete({
3    index: this.indexName,
4    type: this.type,
5    id: id
6  })
7  .then((res) => id);
8}
94. Run test; It should be green.

We are now able to destroy the post with the specified identifier.

5. Create test code for nonexistent resource:

text

1context('when there is no post with the specified id', () => {
2  //ES returns "found" equals false if is not able to find resource
3  //with the specified identifier.
4  before(() =>
5    client.delete = () =>
6      new Promise((resolve, reject) =>
7        resolve({
8          "found": false,
9          "_index": "index",
10          "_type": "type",
11          "_id": id,
12          "_version": 6
13        })
14      )
15  );
16
17  //checks that promise is rejected
18  it('returns rejected promise with the non existing post id', () =>
19    posts.destroy(id).catch((result) =>
20      result.should.equal(id)
21    )
22  );
23});

6. Check functionality:

text

1destroy(id) {
2  return this.client.delete({
3    index: this.indexName,
4    type: this.type,
5    id: id
6  })
7  .then((res) =>
8    new Promise((resolve, reject) => {
9      if (res.found) {
10        return resolve(id);
11      }
12
13      //reject with the post identifier. 
14      reject(id);
15    })
16  );
17}

7. Run tests. They should be green.

Now we have completed all API functionality. Posts can be created, deleted, updated, and listed. The next section covers clean up.

Refactor Controller

Refactoring is a safe and easy operation in our case because the tests cover it. Right now, we have a repetitive pattern in our

app/controllers/posts.js:

text

1{
2  index: this.indexName,
3  type: this.type
4  ...
5}

Let's try to DRY it and clean it up.

1. Extract all such patterns into a dedicated class:

app/lib/resource.js:

sql

1const _ = require('lodash');
2
3module.exports = class {
4  constructor(client, indexName, type) {
5    this.client = client;
6    this.baseParams = { index: indexName, type: type };
7  }
8
9  search() {
10    return this.client.search(this.baseParams);
11  }
12
13  create(attrs) {
14    return this.client.index(_.merge({ body: attrs }, this.baseParams));
15  }
16
17  get(id) {
18    return this.client.get(_.merge({ id: id }, this.baseParams));
19  }
20
21  update(id, attrs) {
22    return this.client.update(_.merge({ id: id, doc: attrs }, this.baseParams));
23  }
24
25  delete(id) {
26    return this.client.delete(_.merge({ id: id }, this.baseParams));
27  }
28};

Our controller has now been simplified a bit:

sql

1const _ = require('lodash');
2const Resource = require('../lib/resource');
3
4module.exports = class {
5  constructor(client, indexName, type) {
6    this.resource = new Resource(client, indexName, type);
7  }
8
9  index() {
10    return this.resource.search()
11      .then((res) =>
12        _.map(res.hits.hits, (hit) =>
13          _.merge(hit._source, { id: hit._id })
14        )
15      );
16  }
17
18  create(attrs) {
19    return this.resource.create(attrs)
20      .then((res) =>
21        _.merge({ id: res._id }, attrs)
22      );
23  }
24
25  show(id) {
26    return this.resource.get(id)
27      .then((res) =>
28        new Promise((resolve, reject) => {
29          if (res.found) {
30            return resolve(_.merge({ id: res._id }, res._source));
31          }
32
33          reject(id);
34        })
35      );
36  }
37
38  update(id, attrs) {
39    return this.resource.update(id, attrs)
40      .then((res) =>
41        new Promise((resolve, reject) => {
42          if (res._id) {
43            return resolve(_.merge({ id: res._id }, attrs));
44          }
45
46          reject(id);
47        })
48      );
49  }
50
51  destroy(id) {
52    return this.resource.delete(id)
53      .then((res) =>
54        new Promise((resolve, reject) => {
55          if (res.found) {
56            return resolve(id);
57          }
58
59          reject(id);
60        })
61      );
62  }
63};

We have extracted all our interactions into a special, dedicated Resource class. But results parsing is still in the controller. Let’s address this.

2. Extract results parsing into a special Parser class:

app/lib/parser.js:

typescript

1const _ = require('lodash');
2
3module.exports = class {
4  parseSearchResult(res) {
5    return _.map(res.hits.hits, (hit) =>
6      _.merge(hit._source, { id: hit._id })
7    );
8  }
9
10  parseCreateResult(attrs) {
11    return (res) => _.merge({ id: res._id }, attrs);
12  }
13
14  parseGetResult(res) {
15    return new Promise((resolve, reject) => {
16      if (res.found) {
17        return resolve(_.merge({ id: res._id }, res._source));
18      }
19
20      reject(res._id);
21    });
22  }
23
24  parseUpdateResult(id, attrs) {
25    return (res) =>
26      new Promise((resolve, reject) => {
27        if (res._id) {
28          return resolve(_.merge({ id: res._id }, attrs));
29        }
30
31        reject(id);
32      });
33  }
34
35  parseDeleteResult(id) {
36    return (res) =>
37      new Promise((resolve, reject) => {
38        if (res.found) {
39          return resolve(id);
40        }
41
42        reject(id);
43      });
44  }
45};

Here is the result:

sql

1const Resource = require('../lib/resource');
2const Parser = require('../lib/parser');
3
4module.exports = class {
5  constructor(client, indexName, type) {
6    this.resource = new Resource(client, indexName, type);
7    this.parser = new Parser();
8  }
9
10  index() {
11    return this.resource.search().then(this.parser.parseSearchResult);
12  }
13
14  create(attrs) {
15    return this.resource.create(attrs).then(this.parser.parseCreateResult(attrs));
16  }
17
18  show(id) {
19    return this.resource.get(id).then(this.parser.parseGetResult);
20  }
21
22  update(id, attrs) {
23    return this.resource.update(id, attrs).then(this.parser.parseUpdateResult(id, attrs));
24  }
25
26  destroy(id) {
27    return this.resource.delete(id).then(this.parser.parseDeleteResult(id));
28  }
29};

Our controller looks much better now!

Summary

We have now completed a Node.js API for an ES by following step-by-step instructions led by testing. The result is a relatively simple API with reliable test coverage. Each of the steps described is trivial and might be done quite easily without any debugging efforts. The TDD approach I have detailed results in better, cleaner code when developing Node.js applications. Once you try it, you will see it is also faster than creating code before the test.

A step-by-step guide for development of Node.js APIs

Proposed Architecture

Set Up Architecture

Install Test Framework, Create First Test, Define Server

Develop and Test Server

Prepare Server for Content Testing

Test Server

Add Support to Create New Post Instance

Develop and Test Controller

Prepare Controller for Testing

Test Controller

Test Parameters

Create and Run Manual Integration Tests

Implement Post Indexing in ES

Implement “Show” Action

Enable “Update” Function

Enable “Destroy” Function

Refactor Controller

Summary

More to read

How to Choose an AI Software Development Company (And What to Watch Out For)

When to Replace Your SaaS Tools with Custom AI Software (And How to Know It's Time)

Exploring the Integration of AI in Software Development: A Full-Stack Developer's Perspective

Healthcare Software Interoperability is Critical: How to Achieve It

We'd love to hear from you!