## Create and maintain API projects ### Create new projects In order to generate a new REST API project, execute the following command: $ rest-tool create 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](http://en.wikipedia.org/wiki/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](https://github.com/raycmorgan/Mu) format, using partials. The stylesheet is based on [sass](http://sass-lang.com/)/[compass](http://compass-style.org/). If you want to change the CSS, modify the files under the `templates/docs/sass` directory. - __templates/test__ : JavaScript test-case ([Mustache](https://github.com/raycmorgan/Mu)) 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](http://visionmedia.github.io/mocha/) and [Jenkins](http://jenkins-ci.org/). 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](https://github.com/tombenke/rest-tool-common/blob/master/schemas/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: 1. Install the newest version of the `rest-tool`. 2. Generate a new, empty project with the new version. 3. 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`. 4. Merge the new module dependencies might found in the new version of `package.json` to the old `projects' package.json`. 5. Copy/merge the templates folder from the new project to the old project. 6. Copy/merge the server folder from the new project to the old project. 7. Merge the config.yml file from the new project to the config.yml file of the old project. 8. 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. After executing the command, you should execute the merging of changes (steps: 4-8). You can remove the `orig` folder, when everything is successfully merged, and running.