rest-tool

Create and maintain API projects

Create new projects

In order to generate a new REST API project, execute the following command:

$ rest-tool create <project-name>

for example:

$ rest-tool create crm-api

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

Now the project is ready to define new services, to run and test them, as well as to generate HTML documentation of them.

The structure of a project

The REST API project layout generated by the rest-tool utility looks like this:

crm-api/
├── docs
├── server
├── services
│   └── monitoring
│       └── isAlive
├── templates
│   ├── docs
│   │   ├── images
│   │   ├── js
│   │   │   └── jquery-1.9.0
│   │   ├── sass
│   │   │   └── partials
│   │   └── stylesheets
│   ├── server
│   ├── services
│   │   ├── COLLECTION
│   │   ├── OPERATION
│   │   └── RESOURCE
│   └── test
└── test

In most of the cases the configuration files, service descriptors and even the schema files are written in YAML format. Content-wise YAML fully covers the capabilities of JSON but it is a more human readable format. Also it offers some extra features that JSON can not provide, such as referencing reusable content, which helps to avoid unnecessary copy-paste.

The role of the of the directories and files:

config.yml :
It holds the configuration parameters of the REST API project. See below the detailed description of the format of this file.
server :
This folder contains the mock server with the mock implementation of the API.
services :
This folder contains the service descriptors. Each service should be put into its own sub-folder, and must have a service.yml file in it. All the other supplementary files, which belongs to the specific service, and used to the specification must be put here, beside the service.yml file. Such files are for example the test-data and schema files.

The service implementation files, which are referred by the service.yml via the implementation fields should be put beside the server code, and not here.
docs :
Contains the HTML format documentation of the REST API. This folder will be totally removed, and recreated during updating the documentation, so you should not modify its content manually.
templates :
This holds the customizable templates used by the documentation generator and the test case generator.
templates/docs :
Documentation templates, stylesheets, and images that the tool is using to create the HTML format documentation. They are written in Mustache format, using partials.

The stylesheet is based on sass/compass. If you want to change the CSS, modify the files under the templates/docs/sass directory.
templates/test :
JavaScript test-case (Mustache) templates to generate unit test code, which will run with mocha and supertest. These are referred from the service descriptors by their names. You can put here any number of additional templates.
templates/services :
Service descriptor templates in YAML format organized by the three main classes of services: COLLECTION, RESOURCE and OPERATION. Each stereotype has its own subdirectory, containing the service.yml template as well as some predefined test data files.
test :
The test cases generated by the rest-tool utility using the service descriptors, and the referred templates.
Makefile :
Makefile to run the test cases. Used by mocha and Jenkins.

In general, you can modify the content of the files and folders the rest-tool create command made, except the files in docs and the test folders, because these will be created and later overwritten by the rest-tool command. If you want to modify the working of the test-cases, the server api implementation or the look-and-feel of the generated documents, you should mostly make changes under the templates and server directories, and of course you will create the service descriptions under the services folder.

The `config.yml` file

This is the default config.yml file created for a new API project:

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

loginCredentials:
    user: username
    pass: password

The config.yml file contains the generic parameters for the services, such as:

projectName: (mandatory, string)
The name of he API project
apiVersion: (mandatory, string)
The actual version number of the API project
author: (mandatory, string)
The author(s) of the API project
licence: (mandatory, string)
Defines the type of the licence for the API
serviceUrlPrefix: (mandatory, string)
The URL prefix commonly used by all the services
servicePort: (mandatory, string)
description: | (mandatory, integer)
The port where the mock server will provide the services and the test agents connects to it.
baseUrl: (mandatory, string)
The base url of the services
servicesRoot: (mandatory, string)
The path to the folder that is the base for the service descriptor sub-folders
services: (mandatory, array)
A list of usb-folders under 'services' that which contain the active services. The list items are relative paths to the service descriptor under the services folder.
loginCredentials: (mandatory, object)
Defines the security credentials for testing.
- user: (mandatory, string)
  The username used for authentication to the mock server
- pass: (mandatory, string)
  The password used for authentication to the mock server

When the server is started, or the generator is used, they check the validity of the config file, so you might get error messages in case of wrong format or missing properties.

To see the detailed schema specification of the config.yml see the serviceConfigSchema.yml file, defined in the rest-tool-common module.

These properties are all available during the documentation and test case generation process in the templates. It is also possible to place additional properties beside the mandatory ones, and they also can be used in templates, so you can customize your documentation or test cases using your own extensional data.

Upgrade an existing API project

The content of the generated projects might change with the new versions of the rest-tool.

A given project is generated to refer to a specific rest-tool-common module, which ensures that the project will work even the rest-tool is significantly changing, however it only guarantees that the server, and the previously generated test cases will work.

In case you are upgrading to a new rest-tool version, the document generation and test case generation may not work any more with an older project. If you would like to leverage the new features, you have to upgrade your old project to the new version.

In order to do this, you can upgrade the old project manually or via the rest-tool upgrade command.

The manual steps are the following:

Install the newest version of the rest-tool.
Generate a new, empty project with the new version.
Replace the version of rest-tool-common in the old project's package.json with the new value found in the newly generated project's package.json.
Merge the new module dependencies might found in the new version of package.json to the old projects' package.json.
Copy/merge the templates folder from the new project to the old project.
Copy/merge the server folder from the new project to the old project.
Merge the config.yml file from the new project to the config.yml file of the old project.
Regenerate the docs and test cases.

In case, you are using the rest-tool upgrade command, you have to execute it in the project root folder. The steps are mainly similar to the manual process, but you can skip the steps: 2-3. The tool will make a copy of the current files and directories into a subdirectory named orig. Then overwrites the files that changed since the last upgrade. The services folder will not change, so there is no copy made on it.