Seahorse is a configurable mock REST API. I may be used for testing and it is written in javascript.

% npm install seahorse --save

% npm install -g seahorse

Start a mock REST API server with a configuration file (config.json) that listen on port 3000 and displays 'apache-like' logs.

var server = require('seahorse');
console.log("Start seahorse server");
server.init('config.json', 3000, {"logs": true});

The initialization function prototype is :

server.init(file, port, options)

• file (string) : can be both an absolute or a relative path to a configuration file
• port (number) : allow to specify the port of the express server
• options (object) : can activate extra functionnalities:
  • traces (boolean) : activates debug traces
  • logs (boolean) : activates apache logs traces
  • cors (boolean) : configures cors directives

Start a mock REST API server with no configuration (no route defined) that listen on port 3000 by default.

% seahorse

Start a mock REST API server with a configuration file (config.json) that listen on port 4000.

% seahorse -f config.json -p 4000

Display help.

% seahorse config.json -h
Usage: seahorse [options] [-f <source>]

Options:
  --help    -h          display this text
  --version -v          output version
  --file    -f <source> load configuration file
  --logs    -l          activate logs   (default: no log)
  --trace   -t          activate traces (default: no trace)
  --nocors  -n          deactivate CORS (default: activated)
  --port    -p <port>   set port
  --rec     -r <output> works like a proxy ans records all requests in a output file

Examples:
  seahorse -f config.json
  seahorse --port 1234

var server   = require('../vendor/seahorse.min').server;

var config = [
  {
    "httpRequest" : {
        "method" : "get",
        "path" : "/foo"
    },
    "httpResponse" : {
        "statusCode" : 200,
        "body" : "{\"key\": \"value\"}",
        "headers" : [ {
            "name": "Access-Control-Allow-Headers",
            "values": ["Content-Type, Authorization"]
        },
        {
            "name": "Content-Type",
            "values": ["application/json; charset=utf-8"]
        } ],
        "delay": 1
    }
  }
];

server.start(config, 3000);

See example/example.js for a very simple use of the lib.

The configuration file contains an array of route objects. Every route object is built with two keys: httpRequest witch make seahorse check if a request matches with this route, and httpResponse that gives seahorse the appropriate response to send in case the request matches the route.

Read the configuration file schema to check the JSON syntax.

The httpRequest key has a value that is an object that shall contains two keys: method (get, post, put or delete) and path. The path key may be either a simple string ("path": "/foo/api.json") or a regexp. To use regexp as route path, you shall prefix the regexp with a string "regexp:" ("path" : "regexp:^/foo/.*.json$") The previous example will match /foo/bar.json and /foo/bar/bas.json but will not match /foo.json neither foo/bar.jsonx

In addition, query parameters may be specified. The query key is an object in witch each key is a parameter with its value.

For example, the following httpRequest object :

httpRequest: {
  method: "get",
  path: "/foo",
  query: {
    "name": "john"
  }
}

Will math GET /foo?name=john, but will not match GET /foo, GET /foo?name=jack, GET /bar?name=john or POST /foo?name=john

The httpResponse is an object that specify, if the request matches the httpRequest object:

• the status code to be sent in the response with the key statusCode,
• the payload can be specified with one of these keys
  • body : object to be returned in the response payload,
  • file : path of a static local file to be returned in the response payload,
  • static : local root path to search for resources to be returned in the response payload (for example, if path equals /foo/bar.txt and static equals /home/jtbonhomme/seahorse/static, the seahorse will serve the file /home/jtbonhomme/seahorse/static/foo/bar.txt)
• optionnaly, in case of static file shall be served (use of file or static), you can specify a maximum bandwidth (in bytes per seconds) to serve the file. Use the route POST /rate to limit the bandwidth.
• optionnaly, some headers to be added to the response,
• and, optionnaly, a delay that will simulate server latency can be added.

See example/config.json :

[{
  "httpRequest" : {
      "method" : "get",
      "path" : "/help",
      "query" : {
        "id": 1,
        "format": "json"
      }
  },
  "httpResponse" : {
      "statusCode" : 200,
      "file":"/Users/jean-thierrybonhomme/Developments/seahorse/lib/help.txt",
      "headers" : [ {
          "name": "Access-Control-Allow-Headers",
          "value": "Content-Type, Authorization"
      },
      {
          "name": "Content-Type",
          "value": "text/plain"
      } ],
      "delay": 2000
  }
}]

Seahorse uses a specific route for its internal needs (_config) Obviously, you can not use this path for your own needs.

Once you started seahorse (given you started it on localhost:3000), you can call /_config:

Return the current configuration

% curl "https://localhost:3000/_config"
[{"httpRequest":{"method":"delete","path":"/help"},"httpResponse":{"statusCode":200,"body":"{\"key\": \"value\"}","headers":[{"name":"Access-Control-Allow-Headers","value":"Content-Type, Authorization"},{"name":"Content-Type","value":"application/json; charset=utf-8"}],"delay":1}}]

Set a new configuration

% curl -X POST --data '[{"httpResquest":...}]' "https://localhost:3000/_config"

Update the configuration. If new routes are specified, they will be added, else, current routes will be updated.

% curl -X PUT --data '[{"httpResquest":...}]' "https://localhost:3000/_config"

Update the maximum bitrate of the server for static resources serving. By default, the max bitrate is 2MBps (2 * 1000 * 1000 / 8 bit per second)

% curl "https://localhost:3000/_rate/5000 -X POST"
{"rate":5000}

Get the current bitrate.

% curl "https://localhost:3000/_rate"
{"rate":250000}

A SSE functionnality is available on route get /stream.

Any event can be fired to all listeners with the route post /stream/:event_name Take care, for now, data SHALL be in JSON format.

To simulate a SSE event sent by the mock API, try :

curl -X POST -H "Content-Type: application/json" --data '{"data":{"326":[18,8,true,false]}, "signal":"LastChange"}' localhost:3000/stream/message

Launch tests with :

% grunt test

The build task will compile the seahorse 'vendor' library (/vendor/seahorse.js and /vendor/seahorse.min.js)

• build and test

% grunt build

• build only

% grunt build:only

• install locally seahorse

% grunt build
% npm install -g .
% seahorse -f example/config.json -p 8080
% curl -ivvv 'https://127.0.0.1:8080/_config'

This project uses these third packages:

• express
• hippie
• grunt-mocha-test
• should
• grunt-nodemon
• minimist
• node-throttle

The seahorse logo was designed by Les vieux garcons.

• Add unit tests on content-lenght header in responses
• Possible issue when using bandwidth field, no Content-length is sent in the response
• Handle cookies

This software is provided under MIT licence.