rest-tool

Get Started

Installation

Prerequisites:

rest-tool needs Node.js and NPM installed on the machine, before start installing and using it.

If you want to change the stylesheets of the generated documentation of the API, you will need Sass and Compass.

Installation steps

The rest-tool tool can be installed as any other node module, but you have to install to the global node_modules folder, so use the -g switch to npm.

To install rest-tool, execute the following command:

$ npm install -g rest-tool

To check, whether rest-tool is installed successfully, run the following command:

$ rest-tool -V
0.4.5

Usage of the rest-tool utility

To get help, use the -h option:

rest-tool -h

Usage: rest-tool [options] [command]

Commands:

create [options] <project-name> Create a new REST API project
docs [options]         Documentation management
add [options]          Add new service to the project
add-bulk [options]     Add new services to the project in bulk mode
test [options]         Test cases management

Options:

-h, --help     output usage information
-V, --version  output the version number

You can do the following things with rest-tool:

  • Create a new REST API project (rest-tool create).
  • Create services for the API (rest-tool add, rest-tool add-bulk).
  • Generate/Update the HTML format documentation (rest-tool doc --update)
  • Generate/Update the test cases (rest-tool test --update)
  • Use the mock Node.js server for testing, and simulating of the REST API functionality (node server/server.js).

You can get help to any of the commands using the following schema:

$ rest-tool <command> -h

for example:

$ rest-tool docs -h

  Usage: docs [options]

  Options:

    -h, --help                     output usage information
    -u, --update                   Generate the HTML format documentation
    -c, --config <configFileName>  The name of the configuration file (default: config.yml)
    -v, --verbose                  Verbose mode

The following sections describe the usage of the commands in details.

Create your first REST API project

Create the project:

Generate a new REST API project:

$ rest-tool create <project-name>

for example:

$ rest-tool create crm-api

Install the required node modules for the project

After, you have created the new project, move into the new projects folder, and install those node modules, the new project needs:

$ cd crm-api
$ npm install

Start the mock server

Start the mock server from the console:

$ node server/server.js 

The server starts and should write something like this:

{ documentRoot: '../webui',
  port: 3007,
  restapiRoot: '..',
  useRemoteServices: false,
  environment: 'development' }
restapi config: { projectName: 'crm-api',
  apiVersion: 'v0.0.0',
  author: 'TBD.',
  licence: 'TBD.',
  serviceUrlPrefix: '/rest',
  servicePort: 3007,
  baseUrl: 'http://localhost:3007/rest',
  servicesRoot: 'services',
  services: [ '/monitoring/isAlive' ],
  loginCredentials: { user: 'username', pass: 'password' } }
register service GET /monitoring/isAlive
/monitoring/isAlive
Express server listening on port 3007 in development mode

As you can see, the server is running, and listening on 3007 port. It uses a base URL that is: http://localhost:3007/rest and the /monitoring/isAlive service is already registered. It is a predefined service which can be used as an example for defining new services as well as it provides a service that immediately should work, and makes easier the troubleshooting if something is wrong with the creation of the project.

You can see its descriptor under the services folder:

services/
└── monitoring
    └── isAlive
        └── service.yml

Try to call this service with a browser or a command line utility, and you should get a true value as a response:

$ curl http://localhost:3007/rest/monitoring/isAlive
true

Run the tests to check if the server is working properly

Open a new terminal, then go into the newly created 'crm-api' project folder, and generate the test cases using the 'rest-tool':

$ rest-tool test --update
Update test cases or create them, if they are missing.
Existing files will not be overwritten

A new test case should be generated under the 'test' folder, based on the 'templates/test/testDelMethod.mustache' template.

Check whether a test case is really there:

$ tree test/
test/
└── Get Monitoring Is Alive.js

0 directories, 1 file

Run the test case to make sure, it is working:

$ mocha

  .

  ✔ 1 tests complete (24ms)

You can also do it via make:

$ make test


  Successfully checks if server is alive
    ✓ should Successfully checks if server is alive 


  1 passing (22ms)

Generate the HTML format documentation

Generate the documentation for the predefined service with the following command:

$ rest-tool docs --update

The following files will be generated:

$ tree docs
docs
├── images
│   └── grid.png
├── index.html
├── js
│   ├── jquery-1.9.0
│   │   ├── jquery-1.9.0.js
│   │   └── jquery-1.9.0.min.js
│   └── restapidoc.js
├── README.md
├── sass
│   ├── ie.scss
│   ├── partials
│   │   └── _base.scss
│   ├── print.scss
│   └── screen.scss
├── services
│   └── monitoring
│       └── isAlive
│           ├── service.html
│           └── service.yml
└── stylesheets
    ├── ie.css
    ├── print.css
    └── screen.css

9 directories, 15 files

Now you can view the generated documentation with a browser either as a static content opening the docs/index.html or through the server using the http://localhost:3007/docs/ URL.

Create your first service

Create a collection manager service with the following command:

$ rest-tool add -t COLLECTION \
    -p customers \
    -u /customers \
    -n Customers \
    -d "A service to manage the collection of customers"

And check what is created under the services folder:

$ tree services/
services/
├── customers
│   ├── getCollection-responseBody.json
│   ├── postCollection-requestBody.json
│   ├── postCollection-responseBody.json
│   └── service.yml
└── monitoring
    └── isAlive
        └── service.yml

3 directories, 5 files

Add the newly created server to the services list in the config.yml file:

projectName: crm-api
apiVersion: v0.0.0
author: TBD.
licence: TBD.
serviceUrlPrefix: /rest
servicePort: 3007
baseUrl: http://localhost:3007/rest
servicesRoot: services
services:
    - /monitoring/isAlive
    - /customers # Add this entry!!!
    # To add new services,put here the path of
    # the directory that contains the service.yml

loginCredentials:
    user: username
    pass: password

Then you should restart the server, and the service is working with the predefined settings and mock data:

$ curl http://localhost:3007/rest/customers
[
  {
    "id": 1,
    "data": "some mock data"
  },
  {
    "id": 2,
    "data": "some mock data"
  }
]

In order to learn more about creating and configuring services, read the documentation pages.