Node-API
Node-API is an easy to use module for creating APIs. This first version (0.0.1) provides you with an easy to use way to add calls and bind them to paths (e.g. /status).
Usage
Node-API is easy to set up and attempts to provide the best way to allow for customized request handing (similar to an HTTP router).
Adding calls
Adding a call is easy, using api.addCall(path, options, callback) or optionally api.addCall(path, callback):
api;
For the options part, several options can be used:
method: the request method this call allows. Can be either GET or POST. When not set, this defaults to GET
requiredFields: an array containing required fields for this request. For GET requests, these fields will need to be provided in the query string. For POST, these fields need to be available as a JSON object in the request body
authentication: a boolean indicating wether or not to use authentication for this call (see below)
Starting the server
To start the API server, simply use the startServer method:
api;
You can use several options here:
port: the port to run the API on. When this option is omitted, port 80 will be used.
authentication: a method providing authentication. This method receives the request body (query string for GET and JSON body for POST), and should return true if authentication succeeded, or false if it didn't.
authenticationDefaultOn: authentication can be enabled on a per-call basis. To enable global authentication, set this option to true.
ssl: If you wish to use SSL, set this option to true. The following two options must be included if this is set to true!
key: the location of your key file. Should of course be readable by Node.
cert: the location of your certificate file. Should of course be readable by Node.
Error messages
Node-API does some checking on incoming requests. The fowllowing error messages can be sent by Node-API:
400 Bad Request: Sent if the request body is not validly formatted JSON (for POST) or when one or more required fields were not present.
401 Unauthorized: Sent if authentication is enabled and failed.
404 Not Found: Sent if the requested path (e.g. '/status') is not specified.
405 Method Not Allowed: Sent if the request method is not GET or POST, or if the wrong method is used for the request (e.g. GET instead of POST).
Error messages are sent to the requester in JSON format as in the following example:
"error": "404" "message": "Action is not found"
Changelog
Version 0.0.1 (27th of April, 2012)
- Added SSL support using the new ssl, key and cert options for the startServer method
Initial version 0.0.1 (19th of April, 2012)
- Initial commit
To do
- Add support for regular expressions as path identifiers
- Make paths and request methods case insensitive
- Redo authentication to allow for customized error messages
- Make all error messages customizable
Planned for a next version:
- Support multiple output formats (targeted at JSON (as it is now) and XML)
- Support for other request methods (e.g. PUT, DELETE, ...)
- Send the ServerResponse object directly to the addCall callback and send a response by using response.send() instead of using return (more async)
- Make the module more asynchroneous
License
Node-API is available under the MIT license.
This readme will be expanded in the future to provide a more complete documentation.