rstsrv
v1.0.1
Published
A simple REST server
Maintainers
hutReadme
rstsrv
A simple REST server for Node.js applications.
Installation
npm install --save rstsrvUsage
The module exports a constructor method, which will return an instance of a Node.js http.Server. The constructor method takes up to four parameters:
- routes (object[], mandatory): The definition of the routes that the server will handle. See below for details.
- port (number, optional): The server will be bound to this port number. If omitted or set to 0 a random high port will be chosen.
- hostname (string, optional): The server will be bound to this interface. If omitted the server will be bound to :: (IPv6) or 0.0.0.0 (IPv4)
- backlog (number, optional): The maximum length of the queue of pending connections.
Routes
Routes are defined as objects and are passed to the server constructor in an array. If several routes match a request URL, the route with the lowest array index will be used. If no matching route can be found the server will respond with status 404.
Every route definition object has the following structure:
{
match: matcher,
handle: {
METHOD: {
body: payload,
type: mime
}
}
}The matcher is a construct which will be used to determine whether a the route will be used to handle a request URL. If the matcher is a string, the route will be used if the request URL equals the matcher. If the matcher is a regular expression, the route will be used if the request URL matches the expression. The matcher can also be a function taking a single string argument and returning a boolean value. In this case the function will be passed the request URL as parameter. The route will be used if the function returns true.
The handle object contains the response definitions for the distinct http methods. For example, the attribute GET of the handle object will be used to respond to http requests using the GET method. These objects will be called "handlers" henceforth. A handle object may contain several distinct handlers for different http methods.
If the body attribute of the handlers is a string, this string will be used as the response payload. If the body attribute is an object, this object will be transformed into a string and used as the response payload. If the body attribute is a function, this function will be called to handle the request. The request and response objects will be passed to function as parameters. The function is responsible for writing data to the response object and closing it.
The type attribute contains a string defining the Content-Type of the response. It will be ignored if the body attribute is a function.
Example
The following code starts a REST server at port 8080. A GET request to http://localhost:8080/hello.html will be answered with an HTML page containing a "Hello World" message. A POST request to http://localhost:8080/article will result in a "See Other" response redirecting the client to a random URL.
Have a look at examples.js for more examples.
const server = require('rstsrv')([
{
match: '/hello.html',
handle: {
GET: {
type: 'text/html',
body: '<!DOCTYPE html>\n<html><body><h1>Hello World</h1></body></html>'
}
}
},
{
match: (url) => {return '/article' === url},
handle: {
POST: {
body: (request, response) => {
response.writeHead(303, {
Location: '/article/' + Math.floor(Math.random() * 10)
})
response.end()
}
}
}
}
], 8080)