node-http-api

Node-API is an easy to use module for creating APIs in Node.JS

npm install node-http-api
1 downloads in the last week
1 downloads in the last month

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.addCall('/status', { 'method': 'GET' }, function(args, response) {
    response.data1 = 'some Data Here';
    response.data2 = 'someData Here';
    return response;
});

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.startServer({
    port: 80
});

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)

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

  1. Add support for regular expressions as path identifiers
  2. Make paths and request methods case insensitive
  3. Redo authentication to allow for customized error messages
  4. Make all error messages customizable

Planned for a next version:

  1. Support multiple output formats (targeted at JSON (as it is now) and XML)
  2. Support for other request methods (e.g. PUT, DELETE, ...)
  3. Send the ServerResponse object directly to the addCall callback and send a response by using response.send() instead of using return (more async)
  4. 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.

npm loves you