Fork me on GitHub

RESTAS

Framework for web application development in Common Lisp

API Reference

Function restas:start (module &key hostname (port 80) (context (make-context)) acceptor-class ssl-certificate-file ssl-privatekey-file ssl-privatekey-password)

Launches a module for processing HTTP requests. RESTAS supports the concept of virtual hosts and permits placing several sites with different domain names in the context of one process. Serving content on several ports is also possible.

Parameters:

  • module - package designator, identifying module defined with aid of restas:define-module

  • hostname - the host name for request processing

  • port - port for accepting requests

  • context - environment analogous to specified with restas:mount-module, permits customizing module parameters.

  • acceptor-class - determines which class of acceptor objects is created and should be (a symbol naming) a class which inherits from restas:restas-acceptor or restas:restas-ssl-acceptor.

  • ssl-certificate-file - path to SSL certificate file. Lispworks supports using one file containing the key and certificate, in which case the ssl-privatekey-file is not need.

  • ssl-privatekey-file - path to key file in PEM format.

  • ssl-privatekey-password - password (as string) for using key file (or NIL, the default, for no password).

This function can be called more than once with different parameters. If different modules were launched for one and the same combination of host name and port number then route conflicts are possible, and, when they happen, the way request dispatch happens is undefined.

Function restas:reconnect-all-routes ()
Reinitialises request dispatcher. Usually there is no need to call this function directly, because during evaluation of restas:mount-module and restas:define-route it is called automatically.

Special variables

Variable restas:*default-host-redirect*
All requests to unregistered hosts will be redirected to this default host.

Variable restas:*bindings*
The set of parsed variables of the route is stored here.

Variable restas:*module*
Active module the current route being handled belongs to.

Variable restas:*route*
The current route being handled.

Routes

Macro restas:define-route (name (template &key (method :get) content-type) &body body)

Creates new route in the current module

  • name - unique symbol, serving as route identifier. The same symbol cannot be used for different routes.

  • template - URL template for matching a route and a request on its basis. It can contain variables which will be directly available in the body of the route.

  • method - HTTP method to be handled, possible values are :GET :POST, :PUT, :DELETE.

  • content-type - result Content-Type HTTP header.

  • body - handler body can contain arbitrary code; its result is returned to the client (after processing it with restas:render-object).

In the beginning of the route body can be used declarations that are special forms, starting with keyword:

  • :headers - plist with HTTP headers names and values. A union with *default-headers* is used, with route option taking precedence.

  • :render-method - object, used by call to restas:render-object for processing of the result of route handler before serving it to client.

  • :apply-render-method - analogous to :render-method, but is called using apply and not funcall.

  • :requirement - arbitrary function called for checking whether a route and a request match each other. If result is NIL then route is regarded as not satisfying the request.

  • :sift-variables - the list of the lists that consist of the variable name and data-sift parsing rule (e.g. function).

  • :decorators - list of decorators. See Decorators.

  • :additional-variables - declaration with an effect of let, adding to the function keyword parameters to simplify REPL experiments with it.

Example of definition of a trivial route:

(restas:define-route main ("")
  "<h1>Hello world!</h1>"
)

For more details about route definition, see Routes

Function restas:route-symbol (route)
Returns symbol, bound to route object (for example, during request processing such object is bound to restas:*route*).

Function restas:genurl (route-symbol &rest args)

Computes URL of the route on the basis of identifying symbol and the set of values of variables of its URL template (see restas:define-route)

  • route-symbol - route identifier

  • args - sequence (in the plist format) of route variable names and their values.

Example:

(restas:genurl 'my-route
               :arg1 "foo"
               :arg2 "bar"
)

Function restas:genurl* (route &rest args)
This function is analogous to restas:genurl except that the generated URL also includes the host name.

Function restas:redirect (route-symbol &rest args)
Redirects the request with hunchentoot:redirect for URL computed with restas:genurl. The parameters are analogous to those of function restas:genurl.

Function restas:abort-route-handler (obj &key return-code content-typе)
Immediately abort handling the route and pass OBJ to restas:render-object to render a response. If the keyword argument RETURN-CODE is specified then it used to set the HTTP response status to allow you to return a special page (500, 404, etc.) with arbitrary content (by default these pages are formed in a uniform way, regardless of the result returned by the handler).

Modules

Macro restas:define-module (name &rest options)
Initializes a new module, creates new package, adds certain service variables to it, and conducts its initialization.

Function restas:initialize-module-instance ((module context))
It is a generic function that calling when the module is mounted with restas:mount-module and can be used, for example, for additional adjustment of submodule context. It should be placed in the package, defined with aid of restas:define-module.

Function restas:finalize-module-instance ((module context))
Is is a generic function that called at the repeated evaluation of restas:mount-module and can be used e.g. for freeing resources allocated at submodule initialization.

Submodules

Macro restas:mount-module (name (module &rest decorators) &rest bindings)

Defines a submodule.

  • name - identifyer (symbol) of a submodule.

  • module - package designator of the mounted module.

  • decorators - list of decorators. See Decorators.

  • bindings - the set of variables and their values defining the context of submodule. The processing of routes from this submodule will be conducted in this context by using progv.

Example:

(restas:mount-module tmp (#:restas.directory-publisher)
  (restas.directory-publisher:*baseurl* '("tmp"))
  (restas.directory-publisher:*directory* #P"/tmp/")
)

Macro restas:with-module (module &body body)
Lets you execute an arbitrary code at the context of the specified module.

View

Function restas:render-object (drawer object)

Generic method used for processing the data returned by the route handler (specified in the body of restas:define-route). If you didn't specify :render-method parameter for restas:define-route macro then the value of *default-render-method* from the module where the current route being handled was defined (It is automatically created at module definition time by macro restas:define-module and its value is NIL) is used.

For more detailed description see the section View.

Context

To provide modularity RESTAS uses a mechanism similar to Buffer-Local Variables`_ in GNU Emacs.

Macro restas:make-context (&body bindings)

Creates dynamic context bindings of dynamic variables to their values. Example:

(restas:make-context (restas.directory-publisher:*baseurl* '("tmp"))
                     (restas.directory-publisher:*directory* #P"/tmp/")
                     (restas.directory-publisher:*autoindex* t)
)

Function restas:context-add-variable (context symbol &optional value)

Adds a new variable to the context.

  • context - contex

  • symbol - symbol, associated to dynamic variable.

  • value - value of the variable. If unspecified, then the result of a call to symbol-value is used.

Function restas:context-remove-variable (context symbol)
Removes the variable from the context.

Function restas:context-symbol-value (context symbol => value, present-p)
Return the value of a dynamic variable. If the variable is undefined in the context, then for evaluating its value symbol-value is used and present-p is equal to NIL.

Macro restas:with-context (context &body body)
Executes the code in the given context with progv.

Debugging

Function restas:debug-mode-on ()
Sets up the debug mode.

Function restas:debug-mode-off ()
Cancels debug mode.

Variable restas:*max-debugging-threads*
Maximal number of simultaneously debugged threads.

@2009-2011 Moskvitin Andrey