vibe.web.rest

Automatic high-level RESTful client/server interface generation facilities.

This modules aims to provide a typesafe way to deal with RESTful APIs. D's interfaces are used to define the behavior of the API, so that they can be used transparently within the application. This module assumes that HTTP is used as the underlying transport for the REST API.

While convenient means are provided for generating both, the server and the client side, of the API from a single interface definition, it is also possible to use as a pure client side implementation to target existing web APIs.

The following paragraphs will explain in detail how the interface definition is mapped to the RESTful API, without going into specifics about the client or server side. Take a look at registerRestInterface and RestInterfaceClient for more information in those areas.

These are the main adantages of using this module to define RESTful APIs over defining them manually by registering request handlers in a URLRouter:

Automatic client generation: once the interface is defined, it can be used both by the client side and the server side, which means that there is no way to have a protocol mismatch between the two.
Automatic route generation for the server: one job of the REST module is to generate the HTTP routes/endpoints for the API.
Automatic serialization/deserialization: Instead of doing manual serialization and deserialization, just normal statically typed member functions are defined and the code generator takes care of converting to/from wire format. Custom serialization can be achieved by defining JSON or string parameters/return values together with the appropriate @bodyParam annotations.
Higher level representation integrated into D: Some concepts of the interfaces, such as optional parameters or in/out/ref parameters, as well as Nullable!T, are translated naturally to the RESTful protocol.

The most basic interface that can be defined is as follows:

@path("/api/")
interface APIRoot {
    string get();
}

This defines an API that has a single endpoint, 'GET /api/'. So if the server is found at http://api.example.com, performing a GET request to $(CODE http://api.example.com/api/) will call the get() method and send its return value verbatim as the response body.

Public Imports
Members
Detailed Description

Endpoint generation
Manual endpoint specification
Method style
Parameter passing
Default values

See Also
Meta

Source
License
Copyright
Authors

Public Imports

vibe.web.common public import vibe.web.common;: Undocumented in source.

Members

Aliases

after alias after = vibe.internal.meta.funcattr.after: Allows processing the return value of a handler method and the request/response objects.
before alias before = vibe.internal.meta.funcattr.before: Allows processing the server request/response before the handler method is called.

Classes

RestInterfaceClient class RestInterfaceClient(I): Implements the given interface by forwarding all public methods to a REST server.
RestInterfaceSettings class RestInterfaceSettings: Encapsulates settings used to customize the generated REST interface.

Functions

generateRestJSClient void generateRestJSClient(R output, RestInterfaceSettings settings): Generates JavaScript code to access a REST interface from the browser.
getInterfaceValidationError string getInterfaceValidationError(): Undocumented in source.
registerRestInterface URLRouter registerRestInterface(URLRouter router, TImpl instance, RestInterfaceSettings settings)
URLRouter registerRestInterface(URLRouter router, TImpl instance, MethodStyle style)
URLRouter registerRestInterface(URLRouter router, TImpl instance, string url_prefix, MethodStyle style): Registers a server matching a certain REST interface.
serveRestJSClient HTTPServerRequestDelegate serveRestJSClient(RestInterfaceSettings settings)
HTTPServerRequestDelegate serveRestJSClient(URL base_url)
HTTPServerRequestDelegate serveRestJSClient(string base_url): Returns a HTTP handler delegate that serves a JavaScript REST client.
stripTUnderscore string stripTUnderscore(string name, RestInterfaceSettings settings): Undocumented in source. Be warned that the author may not have intended to support it.

Structs

Collection struct Collection(I): Models REST collection interfaces using natural D syntax.

Templates

GenCmp template GenCmp(string name, int id, string cmpTo): Undocumented in source.

Detailed Description

Endpoint generation

An endpoint is a combination of an HTTP method and a local URI. For each public method of the interface, one endpoint is registered in the URLRouter.

By default, the method and URI parts will be inferred from the method name by looking for a known prefix. For example, a method called getFoo will automatically be mapped to a 'GET /foo' request. The recognized prefixes are as follows:

Prefix	HTTP verb
get	GET
query	GET
set	PUT
put	PUT
update	PATCH
patch	PATCH
add	POST
create	POST
post	POST

Member functions that have no valid prefix default to 'POST'. Note that any of the methods defined in vibe.http.common.HTTPMethod are supported through manual endpoint specifications, as described in the next section.

After determining the HTTP method, the rest of the method's name is then treated as the local URI of the endpoint. It is expected to be in standard D camel case style and will be transformed into the style that is specified in the call to registerRestInterface, which defaults to MethodStyle.lowerUnderscored.

Manual endpoint specification

Endpoints can be controlled manually through the use of @path and @method annotations:

@path("/api/")
interface APIRoot {
    // Here we use a POST method
    @method(HTTPMethod.POST)
	// Our method will located at '/api/foo'
	@path("/foo")
	void doSomething();
}

Manual path annotations also allows defining custom path placeholders that will be mapped to function parameters. Placeholders are path segments that start with a colon:

@path("/users/")
interface UsersAPI {
    @path(":name")
    Json getUserByName(string _name);
}

This will cause a request "GET /users/peter" to be mapped to the getUserByName method, with the _name parameter receiving the string "peter". Note that the matching parameter must have an underscore prefixed so that it can be distinguished from normal form/query parameters.

It is possible to partially rely on the default behavior and to only customize either the method or the path of the endpoint:

@method(HTTPMethod.POST)
void getFoo();

In the above case, as 'POST' is set explicitly, the route would be 'POST /foo'. On the other hand, if the declaration had been:

@path("/bar")
void getFoo();

The route generated would be 'GET /bar'.

Properties: @property functions have a special mapping: property getters (no parameters and a non-void return value) are mapped as GET functions, and property setters (a single parameter) are mapped as PUT. No prefix recognition or trimming will be done for properties.

Method style

Method names will be translated to the given 'MethodStyle'. The default style is MethodStyle.lowerUnderscored, so that a function named getFooBar will match the route 'GET /foo_bar'. See vibe.web.common.MethodStyle for more information about the available styles.

Parameter passing

By default, parameter are passed via different methods depending on the type of request. For POST and PATCH requests, they are passed via the body as a JSON object, while for GET and PUT they are passed via the query string.

The default behavior can be overridden using one of the following annotations:

@headerParam("name", "field"): Applied on a method, it will source the parameter named name from the request headers named "field". If the parameter is ref, it will also be set as a response header. Parameters declared as out will only be set as a response header.
@queryParam("name", "field"): Applied on a method, it will source the parameter name from a field named "field" of the query string.
@bodyParam("name", "field"): Applied on a method, it will source the parameter name from a field named "feild" of the request body in JSON format.

@path("/api/")
interface APIRoot {
	// GET /api/header with 'Authorization' set
	@headerParam("param", "Authorization")
	string getHeader(string param);

	// GET /api/foo?param=...
	@queryParam("param", "param")
	string getFoo(int param);

	// GET /api/body with body set to { "myFoo": {...} }
	@bodyParam("myFoo", "parameter")
	string getBody(FooType myFoo);
}

Default values

Parameters with default values behave as optional parameters. If one is set in the interface declaration of a method, the client can omit a value for the corresponding field in the request and the default value is used instead.

Note that this can suffer from DMD bug #14369 (Vibe.d: #1043).

Aggregates: When passing aggregates as parameters, those are serialized differently depending on the way they are passed, which may be especially important when interfacing with an existing RESTful API:

If the parameter is passed via the headers or the query, either implicitly or explicitly, the aggregate is serialized to JSON. If the JSON representation is a single string, the string value will be used verbatim. Otherwise the JSON representation will be used
If the parameter is passed via the body, the datastructure is serialized to JSON and set as a field of the main JSON object that is expected in the request body. Its field name equals the parameter name, unless an explicit @bodyParam annotation is used.