Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
branch: master
Fetching contributors…

Cannot retrieve contributors at this time

file 206 lines (112 sloc) 5.561 kb

dREST

To use the dREST server one must install the drest npm module and var drest = require('drest').

The dREST interface is built on top of the node.js HTTP interface. It is built for the rapid development of RESTful web services in node.

drest.createRouter(port, [hostname])

Returns a new Router object

hostname default value is "127.0.0.1"

drest.Router

This object is created from the drest.createRouter method.

router.allowJSONP

Boolean value that when set to true allows requester to set the url argument 'callback' and wrap the response in a function call

Example: Set url query to ?callback=doOnReturn

Default value is true

router.responseContentType

String value to set the response header ContentType default.

Default value is "application/javascript"

router.addRoute(object)

Returns a new Route object

Valid argument object values are any Route object value

Recommended argument object values to set are method, path, action, and typically authLevel if the route requires an authentication layer

router.setAuthLayer(callback)

callback returns a passthrough Handler object. An authorization level scheme should be executed inside the callback to test whether requester has authorization to execute the route. A number signifying authority level must be returned in the scheme's callback method arguments and passthrough.check(*number*) must be executed upon authority level check completion.

Example:

     router.setAuthLayer(
        function(passthrough) {

            if( test_token_validity(passthrough) ) {
                some_generic_database.execute(
                    "get authority_level from users where token = `passthrough.query['token']`", 
                    function(response_from_generic_database) {
                        passthrough.check(response_from_generic_database);
                    }
                );
            }else{
                passthrough.check(0);
            }
        }
    );

drest.Router.defaultResponses

Object containing a group of common HTTP status codes in the form of objects used by the handler.respondWithDefault method

One can add a response in the following way:

    drest.Router.defaultResponses["I'm a teapot"] = {status:418, message:"Any attempt to brew coffee with a teapot should result in the error code \"418 I'm a teapot\". The resulting entity body MAY be short and stout."};

drest.Route

This object is created from the router.addRoute method.

route.method

HTTP method such as GET, POST, PUT, DELETE

Default value is get

route.path

String containing ordered path conditions separated by / for matching a url

Example:

"user/{'string'}/status/*" would allow the url http://localhost/user/yoshimi/status/karateBeltColor to pass

"robot/listByColor/{'^.*\\b(pink|maroon|red)\\b.*$'}/{'number'} would allow the url http://localhost/robot/listByColor/pink/3000 to pass

a url must meet all conditions in order to pass

route path conditions

someText passes if value is exactly 'someText'

{number} passes if value is a number

{string} passes if value is a string and not a number

* value always passes

{'^[a-zA-Z]*$'} passes if value matches a {'regular expression'}. Letters only in this example

route.name

Route name identifier

route.authLevel

Number to determine if requester has authorization to access route. See router.setAuthLayer method for more details

Default value is 0

route.action

Function reference called when a url matches route.path pattern and authorization is cleared

route.authAction

Custom authorization layer method called instead of default router AuthLayer when a url matches route.path pattern.

route.status

HTTP status code on route response

Default value is 200

route.storage

Object for storing user defined values

drest.Handler

This object is created when a requester makes a request to the server. The object's values are set during the route process, and passed to the route.action method

handler.request

The current node.js http.ServerRequest object

handler.response

The current node.js http.ServerResponse object

handler.route

The current route object

handler.data

Data string sent from a POST or PUT request

handler.query

Object created from url query

?v=1.1&debug=true becomes {v:"1.1",debug:"true"}

handler.queryString

String from url query

handler.headers

Object of request headers

handler.status

The response status code (usually set by route.status)

handler.path

Array containing url path strings

handler.addHeader(name, value)

Adds a response header

name : The response header name (Access-Control-Allow-Origin, Keep-Alive)

value : The response header value (*, timeout=2, max=100)

handler.respond(body)

Sends a final response to the requester

body : Either a string or an object (will be stringified if an object)

handler.respondWithDefault(status, [expanded])

Send a final response to the requester with a value set from Router.defaultResponses

status : String matching defaultResponses key

expanded : Optional boolean sends an extended message

handler.check(authLevel)

Also known as passthrough.check(authLevel)

Called during a default authLayer check (see router.setAuthLayer for more info)

Something went wrong with that request. Please try again.