LocalAPI

Tutorial

Check out our wiki and tutorial for LocalAPI!

• Wiki Home
• Tutorial

Table of Contents

• Installation
• Usage
  • Run options
    • Custom port
    • Show running details
    • Use static examples
• RAML
  • Version
  • Directory structure
  • Supported responses
• Dummy data generator
  • Basic Information
  • How to
  • Methods for template generator
• Known problems and limitations
• Planned features and enhancements
• License
• Changelog

Installation

1. Install Node.js from http://nodejs.org/, version 0.9.11 or higher
2. Install LocalAPI module via npm

npm install -g localapi

Usage

1. Create a RAML directory with the specified structure

2. Enter the RAML directory:

cd example_raml

3. Run LocalAPI:

localapi [options] run <raml-file>

4. 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

See Example RAML directory.

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

1. Create JavaScript templates in /templates directory (see example).

2. 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: 24

  var id = tmplUtils.stringId();
  // id === rd9k0cgdi7ap2e29

• tmplUtils.getTemplate(template_filename) Generates and includes dummy data json from the template. template_filename - path to template file

  var 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 array

  var 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.