registerWebInterface

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

Each public method of the given class instance will be mapped to a HTTP route. Property methods are mapped to GET/PUT and all other methods are mapped according to their prefix verb. If the method has no known prefix, POST is used. The rest of the name is mapped to the path of the route according to the given method_style. Note that the prefix word must be all-lowercase and is delimited by either an upper case character, a non-alphabetic character, or the end of the string.

The following table lists the mappings from prefix verb to HTTP verb:

HTTP methodRecognized prefixes
GETget, query
PUTset, put
POSTadd, create, post
DELETEremove, erase, delete
PATCHupdate, patch

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 vibe.http.server.HTTPServerRequest.params map.

The latter can be used to inject custom data in various ways. Examples of this are placeholders specified in a @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.

registerWebInterface
(
C : Object
MethodStyle method_style = MethodStyle.lowerUnderscored
)

Parameters

router URLRouter

The HTTP router to register to

instance C

Class instance to use for the web interface mapping

settings WebInterfaceSettings

Optional parameter to customize the mapping process

Detailed Description

Parameter conversion rules

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

  • A dynamic array of values is mapped to <parameter_name>_<index>, where index denotes the zero based index of the array entry. Any missing indexes will be left as their init value. Arrays can also be passed without indexes using the name <parameter_name>_. They will be added in the order they appear in the form data or query. Mixed styles can also be used, non-indexed elements will be used to fill in missing indexes, or appended if no missing index exists. Duplicate indexes are ignored
  • A static array of values is mapped identically to dynamic arrays, except that all elements must be present in the query or form data, and indexes or non-indexed data beyond the size of the array is ignored.
  • 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 std.conv.to!T.
  • Any of these rules can be applied recursively, so that it is possible to nest arrays and structs appropriately. Note that non-indexed arrays used recursively will be ignored because of the nature of that mechanism.

Special parameters

Supported attributes

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

@before, @after, @errorDisplay, @vibe.web.common.method, @vibe.web.common.path, @vibe.web.common.contentType

The @path attribute can also be applied to the class itself, in which case it will be used as an additional prefix to the one in WebInterfaceSettings.urlPrefix.

The @nestedNameStyle attribute can be applied only to the class itself. Applying it to a method is not supported at this time.

Supported return types:

  • vibe.data.json.Json
  • const(char)[]
  • void
  • const(ubyte)[]
  • vibe.core.stream.InputStream

Examples

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;
	}

	@path("/")
	void getIndex(string _error = null)
	{
		header("Access-Control-Allow-Origin", "Access-Control-Allow-Origin: *");
		//render!("index.dt", _error);
	}

	// automatically mapped to: POST /login
	@errorDisplay!getIndex
	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;
		redirect("/profile");
	}

	// automatically mapped to: POST /logout
	void postLogout()
	{
		terminateSession();
		status(201);
		redirect("/");
	}

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

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

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

Meta