View the docs on Docs
Working with APIs, more often than not, during development you want to work with a fixed version of the responses provided. This is especially true if the API is still under development, and maybe even still needs input on how to output something. This is what Canned is for!
Canned maps a folder structure to API responses
/comment/any.get.json
/comment/index.get.html
requests like
GET /comment/:id
are served as
Content-Type: application/json
{ "content": "I am a comment", "author": "sideshowcoder" }
requests like
GET /content/
are served as
Content-Type: text/html
<html>
<body>Some html in here</body>
</html>
Currently Canned supports the basic REST-API mapping, as well as custom method mapping with nested endpoints.
file | resquest
/index.get.json | GET /
/any.get.json | GET /:id
/_search.get.json | GET /search
/comments/index.get.json | GET /comments/
/comments/any.get.json | GET /comments/:id
/comments/_search.get.json | GET /comments/search
You can even add query parameters to your filenames to return different responses on the same route. If the all query params in a filename match the incoming request, this file will be returned. It will fall back to returning the file with no query params if it exists.
Warning this will be deprecated in the future since canned now supports multiple response based on the request body or GET URL parameters in one file. This is the prefered way since files with ? in the name do not work on Windows
file | resquest
/index?name=Superman.get.json | GET /?name=Superman&NotAllParams=NeedToMatch
/_search?q=hello.get.json | GET /comments/search?q=hello
/_search.get.json | GET /comments/search?iam=soignored
Same support is available for PUT, POST, etc.
/index.post.json | POST serves /... + CORS Headers
/index.put.json | PUT serves /... + CORS Headers
If CORS support is enabled additionally options will be available as a http verb and all requests will serve the CORS Headers as well
/ | OPTIONS serve all the options needed for CORS
/index.get.json | GET serves /... + CORS Headers
If you need some custum return codes, just add them to the file via adding a file header like so
//! statusCode: 201
<html>
<body>Created something successfully! Happy!</body>
</html>
The header will be stripped before sending and the statusCode will be set.
You can also override the default content types by adding a custom content type to the file header:
//! contentType: "application/vnd.custom+xml"
<xml>
<created>1</created>
</xml>
This will be returned with a Content-type: application/vnd.custom+xml header.
Multiple headers need to be written on one single line and comma-separated, like so:
//! statusCode:201, contentType: "application/vnd.custom+xml"
You can get a different response by specifying request data in variant comments. If the request data matches the comment data the matching response is returned. If there is no match the first response is returned
Note: comments must be on a single line
Custom headers:
//! header: {"authorization": "abc"}
{
"response": "response for abc"
}
//! header: {"authorization": "123"}
{
"response": "response for 123"
}
If you need different responses based on request body then you can specify the request you want matched via body comments:
//! body: {"email": "[email protected]"}
{
"response": "response for [email protected]"
}
//! body: {"email": "[email protected]"}
{
"response": "response for [email protected]"
}
If you need different responses based on request parameters then you can specify them via parameters comments:
//! params: {"foo": "bar"}
{
"response": "response for bar"
}
//! params: {"foo": "baz"}
{
"response": "response for baz"
}
this would match http://my.local.server/my_get_request_path?foo=bar or
http://my.local.server/my_get_request_path?foo=baz respectively.
To use in conjunction with response headers, list the response header first.
//! statusCode: 201
//! header: {"authorization": "abc"}
{
"response": "response for abc"
}
//! header: {"authorization": "123"}
{
"response": "response for 123"
}
Most content types support comments natively, like html or javascript. Sadly the probably most used type (JSON) does not :(. So canned actually extends the JSON syntax a little so it can include comments with // or /**/. In case you use the JSON files directly on the backend side as test cases make sure you strip those out as well!
Just install via npm
$ npm install canned
which will install it locally in node_modules, if you want to have it available from anywhere just install globally
$ npm install -g canned
There are 2 ways here, either you embed it somewhere programmatically
var canned = require('canned')
, http = require('http')
, opts = { cors: true, logger: process.stdout }
can = canned('/path/to/canned/response/folder', opts)
http.createServer(can).listen(3000)
Or just run the provided canned server script
$ canned
Which serves the current folder with canned responses on port 3000
$ canned -p 5000 ./my/responses/
will serve the relative folder via port 5000
If for whatever reason you want to turn of CORS support do so via
$ canned --cors=false ./my/responses/
Also if you need additional headers to be served alongside the CORS headers these can be added like this (thanks to runemadsen)
$ canned --headers "Authorization, Another-Header"
For more information checkout the pull request
Already using grunt? Great there is a plugin for that, thanks to jkjustjoshing.
make sure you either install globally or put ./node_modules/.bin in your PATH
make sure /usr/local/share/npm/bin is in your path, this should be true for every install since you won't be able to run any global module bins if not. (like express, and such)
make sure you run a version of node which is 0.10.3 or higher, because it fixes a problem for the encoding handling when reading files
- Checkout the repository
- Run the tests and jshint
$ make - Create a topic branch
$ git checkout -b my-new-feature - Code test and make jshint happy!
$ make test$ make hint - Push the branch and create a Pull-Request
I try to review the pull requests as quickly as possible, should it take to long feel free to bug me on twitter
- support for XML headers to support SOAP (@vikalp)
- fix relative path again... (@sideshowcoder)
- fixes for variable responses with JSON body (@bibounde)
- fixes for relative paths on start (@sideshowcoder)
- complex get parameters causing regexp match on file to fail (@sideshowcoder)
- support for multiple responses per file (@hungrydavid)
- support for GET responses without the need for special characters in the filename (@sideshowcoder based on the work by @hungrydavid)
- added support for empty response with 204 for no content (@jkjustjoshing)
- sorry haven't kept a version history, yet. Will now!
- sideshowcoder
- leifg
- runemadsen
- mulderp
- creynders
- jkjustjoshing
- hungrydavid
- bibounde
- vikalp
- simonprickett
MIT 2013 Philipp Fehre alias @sideshowcoder, or @ischi on twitter