vibe.d beta banner
get vibe.d

Asynchronous I/O that doesn’t get in your way, written in D

Template registerWebInterface

Registers a HTTP/web interface based on a class instance.

template registerWebInterface(C, MethodStyle method_style = MethodStyle.lowerUnderscored) ;

Each public method of the given class instance will be mapped to a HTTP route. Method parameters will be sourced from either the query string or form data of the request, or, if the parameter name has an underscore prefixed, from the HTTPServerRequest.params map.

The latter can be used to inject custom data in various ways. Examples of this are placeholders specified in a $D( @path) annotation, values computed by a @before annotation, error information generated by the errorDisplay annotation, or data injected manually in a HTTP method handler that processed the request prior to passing it to the generated web interface handler routes.

Methods that return a class or interface instance, instead of being mapped to a single HTTP route, will be mapped recursively by iterating the public routes of the returned instance. This way, complex path hierarchies can be mapped to class hierarchies.

Contained Functions

registerWebInterfaceRegisters a HTTP/web interface based on a class instance.

Parameter conversion rules

For mapping method parameters without a prefixed underscore to query/form fields, the following rules are applied:

  • An array of values is mapped to <parameter_name>_<index>, where index denotes the zero based index of the array entry. The length of the array is determined by searching for the first non-existent index in the set of form fields.
  • Nullable!T typed parameters, as well as parameters with default values, are optional parameters and are allowed to be missing in the set of form fields. All other parameter types require the corresponding field to be present and will result in a runtime error otherwise.
  • struct type parameters that don't define a fromString or a fromStringValidate method will be mapped to one form field per struct member with a scheme similar to how arrays are treated: <parameter_name>_<member_name>
  • Boolean parameters will be set to true if a form field of the corresponding name is present and to false otherwise. This is compatible to how check boxes in HTML forms work.
  • All other types of parameters will be converted from a string by using the first available means of the following: a static fromStringValidate method, a static fromString method, using!T.
  • Any of these rules can be applied recursively, so that it is possible to nest arrays and structs appropriately.

Special parameters

  • A parameter named _error will be populated automatically with error information, when an @errorDisplay attribute is in use.
  • An InputStream typed parameter will receive the request body as an input stream. Note that this stream may be already emptied if the request was subject to certain body parsing options. See HTTPServerOption.
  • Parameters of types HTTPServerRequest, HTTPServerResponse, HTTPRequest or HTTPResponse will receive the request/response objects of the invoking request.

Supported attributes

The following attributes are supported for annotating methods of the registered class:

@before, @after, @errorDisplay, @method, @path, @contentType


router The HTTP router to register to
instance Class instance to use for the web interface mapping
settings Optional parameter to customize the mapping process


Gives an overview of the basic features. For more advanced use, see the example in the "examples/web/" directory.

import vibe.http.router;
import vibe.http.server;
import vibe.web.web;

class WebService {
	private {
		SessionVar!(string, "login_user") m_loginUser;

	void getIndex(string _error = null)
		//render!("index.dt", _error);

	// automatically mapped to: POST /login
	void postLogin(string username, string password)
		enforceHTTP(username.length > 0, HTTPStatus.forbidden,
			"User name must not be empty.");
		enforceHTTP(password == "secret", HTTPStatus.forbidden,
			"Invalid password.");
		m_loginUser = username;

	// automatically mapped to: POST /logout
	void postLogout()

	// automatically mapped to: GET /profile
	void getProfile()
		enforceHTTP(m_loginUser.length > 0, HTTPStatus.forbidden,
			"Must be logged in to access the profile.");

void run()
	auto router = new URLRouter;
	router.registerWebInterface(new WebService);

	auto settings = new HTTPServerSettings;
	settings.port = 8080;
	listenHTTP(settings, router);

Sönke Ludwig


© 2013-2014 RejectedSoftware e.K.


Subject to the terms of the MIT license, as written in the included LICENSE.txt file.