README
LocalAPI **LocalAPI** is a Node.js-based application that allows for running a fully functional API on the basis of definitions contained in a RAML file. LocalAPI also generates dummy data JSON files based on JavaScript templates. Example data is generated every time LocalAPI starts and is utilized as responses in the API module.
Tutorial
Check out our wiki and tutorial for LocalAPI!
Table of Contents
- Installation
- Usage
- RAML
- Dummy data generator
- Known problems and limitations
- Planned features and enhancements
- License
- Changelog
Installation
- Install Node.js from http://nodejs.org/, version 0.9.11 or higher
- Install LocalAPI module via npm
npm install -g localapi
Usage
Create a RAML directory with the specified structure
Enter the RAML directory:
cd example_raml
- Run LocalAPI:
localapi [options] run <raml-file>
- Wait a moment until the RAML file is loaded and JSON files with dummy data are generated. The following information will show:
info: [localapi] App running at http:/0.0.0.0:3333
LocalAPI will run at http://localhost:3333
Run options
Custom port
To run LocalAPI on a custom port use -p
argument
localapi run raml_example_file.raml -p 3500
Show running details
To run LocalAPI with additional logs (details mode) use -d
argument
localapi run -d raml_example_file.raml
Use static examples
To run LocalAPI with your own predefined examples (not generated from templates), use --no-examples
argument
localapi run --no-examples raml_example_file.raml
RAML
Version
As of now, LocalAPI supports RAML 0.8.
Directory structure
- [dir] examples - dummy data JSON files (generated from templates)
- [dir] static_examples - dummy data JSON files (static)
- [dir] schemas - json schemas
- [dir] templates - dummy data templates for the generator
- {YOUR_RAML_FILENAME}.raml - the RAML file
Supported responses
LocalAPI supports:
regular fake data response
Available for for synchronous GET requests. Returns the specified response example file.
get: responses: 200: body: application/json: schema: !include schemas/users.json example: !include examples/users.json
response containing fake data merged with data sent in the body the request
Available for POST, PUT, PATCH requests.
patch: description: Updates a user partially by his/her id. body: application/json: example: !include examples/user_patch.json schema: !include schemas/user_patch.json responses: 200: body: application/json: schema: !include schemas/user.json example: !include examples/user.json
response containing only data sent in the body of the request
Available for POST, PUT, PATCH requests.
put: body: application/json: schema: !include schemas/user_put.json example: !include examples/user.json responses: 200: body: application/json: example: false
empty response
Available for all requests.
post: description: Creates a user with a system-generated id. body: application/json: example: !include examples/user_post.json schema: !include schemas/user_post.json responses: 202: body: application/json: example: "" schema: ""
Dummy data generator
Basic Information
- Template location:
/templates
- Template format:
*.js
- Example data is generated every time LocalAPI starts.
- To disable it, use
--no-examples
option.
TIP - Faker.js library is available to use.
How to
Create JavaScript templates in
/templates
directory (see example).Run LocalAPI to generate JSON files (see Usage).
Methods for template generator
tmplUtils.stringId([string_length])
Returns a string with random characters.
string_length - default: 24var id = tmplUtils.stringId(); // id === rd9k0cgdi7ap2e29
tmplUtils.getTemplate(template_filename)
Generates and includes dummy data json from the template.
template_filename - path to template filevar userData = tmplUtils.getTemplate('user.js'); // userData === {user_data_json}
tmplUtils.multiCollection(min_length, max_length)(loop_function)
Creates an array with a random number of elements between min_length and max_length.
Single item in array is the result of loop_function.
min_length - Minimal length of items in array
max_length - Maximal length of items in array
loop_function - Function that adds a single item to an arrayvar indexArray = tmplUtils.multiCollection(0, 20)(function (i) { return i; }); // indexArray === [0, 1, 2, 3, 4, 5, 6]
var indexArray = tmplUtils.multiCollection(1, 3)(function (i) { return tmplUtils.getTemplate('user.js'); }); // indexArray === [{user_data_json_1}, {user_data_json_2}]
Known problems and limitations
- When defining multiple response status codes for a request, LocalAPI always returns the one with the smallest code number, regarldess of their order in the RAML file.
- As of now, no support RAML 1.0.
- Cannot switch from generated examples to static examples without manually editing the RAML file.
Planned features and enhancements
- Improved writing to the console
- Modular architecture
- Persistence
- Sample RAML generator
- RAML 1.0 support
- Support for query parameters
- Improved exception handling
- Generating documentation
License
To see LocalAPI license, go to LICENSE.md.
Changelog
To see LocalAPI changelog, go to CHANGELOG.md.