Home

Interfake is a flexible, unopinionated tool for creating simple or complex semi-static HTTP APIs. There are three different interfaces for Interfake: the JavaScript API, the Command-Line API and the HTTP API.

Three ways to use Interfake

The JavaScript API useful for NodeJS environments, or if you're a JavaScript developer already. The command line is useful for non-NodeJS environments because it can be called from most places, or if you're not a JavaScript developer. The Interfake HTTP meta-API is also useful for non-NodeJS tests, and is particularly useful when you need to create endpoints dynamically after creating the API.

Method 1: JavaScript

Make sure you've installed Interfake as a local module using npm install interfake --save. If you var Interfake = require('interfake') in your JavaScript file, you can use the following API to spin up the Interfake server.

Example (more examples)

var Interfake = require('interfake');

var interfake = new Interfake();

// Create endpoints using the fluent interface
interfake.post('/items').status(201).body({ created: true }).creates.get('/next-items').status(200).body([ { id: 1, name: 'the thing' } ]);

// Or using the more verbose JSON syntax (more on this below under 'command line')
interfake.createRoute({
	request: {
		url: '/whats-next',
		method: 'get',
		query: { // Optional querystring parameters
			page: 2
		}
	},
	response: {
		code: 200, // HTTP Status Code
		delay: 50, // Delay in milliseconds
		body: { // JSON Body Response
			next:'more stuff'
		},
		headers: { // Optional headers
			'X-Powered-By': 'Interfake'
		}
	}
});

interfake.listen(3000); // The server will listen on port 3000

API

• new Interfake(options): creates an Interfake object. Options are:
  • debug: If true, outputs lots of annoying but helpful log messages. Default is false.
  • path: Sets the API root path. E.g. if api is used then the route at /users will be accessible at /api/path
• #createRoute(route): Takes a JSON object with the following:
  • request
  • response
  • afterResponse (optional)
• #listen(port, callback): Takes a port and starts the server, and a callback which executes when the server is running
• #stop(): Stops the server if it's been started
• #serveStatic(path, directory): Serve static (usually a website) files from a certain path. This is useful for testing SPAs. (Example use.)

Fluent Interface

• #get|post|put|delete(url): Create an endpoint at the specified URL. Can then be followed by each of the following, which can follow each other too e.g. get().query().body().status().body().creates.get() etc.
  • #query(queryParameters): An object containing query parameters to accept. Overwrites matching URL params. E.g. get('/a?b=1').query({b:2}) means /a?b=2 will work but /a?b=1 will not.
  • #status(statusCode): Set the response status code for the endpoint
  • #body(body): Set the JSON response body of the end point
  • #delay(milliseconds): Set the number of milliseconds to delay the response by to mimic network of processing lag
    • Also accepts a delay range in the format 'ms..ms' e.g. '50..100'
  • #responseHeaders(headers): An object containing response headers. The keys are header names.
  • #creates#get|post|put|delete(url): Specify an endpoint to create after the first execution of this one. API is the same as above.
  • #extends#get|post|put|delete(url): Specify an endpoint to modify after the first execution of this one. API is the same as above. The endpoints you extend are matched based on url and query. The status, body, delay and responseHeaders are the extendable bits. Keep in mind that keys will be replaced, and arrays will be added to.

Method 2: Command line

Interfake must be install globally for the command line interface to work:

npm install interfake -g

A JSON array of request/response pairs ("endpoints") you can write APIs and run them multiple times using the global interfake executable, and the JSON syntax.

Example (more examples)

Create a file called adventuretime.json:

[
	{
		"request": {
			"url": "/whattimeisit",
			"method": "get"
		},
		"response": {
			"code": 200,
			"delay": 100,
			"body": {
				"theTime": "Adventure Time!",
				"starring": [
					"Finn",
					"Jake"
				],
				"location": "ooo"
			}
		}
	}
]

Then run Interfake against it:

interfake --file ./adventuretime.json

Now go to http://localhost:3000/whattimeisit in your web browser.

The above example will create a endpoint at http://localhost:3000/whattimeisit which returns a 200 and the body specified in the response object.

The top-level array should contain a list of endpoints (represented by request/response objects). The request object contains a URL and HTTP Method (GET/POST/PUT/DELETE/etc) to match against, and the response object contains an HTTP Status Code (code) and body object, which is in itself a JSON object, and optional. This body is what will be returned in the body of the response for the request you're creating.

You can create as many HTTP request/response pairs as you like. I've put some simple examples below for your copy & paste pleasure, or you can look in /examples-command-line for some more complex examples.

Run interfake --help for a full list of command-line options.

Conditional endpoints

When the API needs to mutate responses, such as after a POST, PUT or DELETE request, there is an afterResponse property available for any existing endpoint, which specifies endpoints to create after the parent has been hit for the first time.

[
	{
		"request": {
			"url": "/items",
			"method": "post"
		},
		"response": {
			"code": 201,
			"body": {}
		},
		"afterResponse": {
			"endpoints": [
				{
					"request": {
						"url": "/items",
						"method": "get"
					},
					"response": {
						"code": 200,
						"body": { "items" : [] }
					}
				}
			]
		}
	}
]

The afterResponse property can be used as deep as you like in the endpoint hierarchy. For a complex example of the use of post-response endpoints, see the /examples-command-line/crud.json file in this repository.

Method 3: HTTP

While the server is running, you can create new endpoints on-the-fly. You can make a POST request to /_requests with the same JSON structure that the command line interface accepts.

Example

While Interfake is running, make this request using curl.

$ curl -X POST -d '{ "request":{"url":"/whattimeisit", "method":"get"}, "response":{"code":200,"body":{ "theTime" : "Adventure Time!" } } }' http://localhost:3000/_requests --header "Content-Type:application/json"