registerRestInterface

Registers a server matching a certain REST interface.

Servers are implementation of the D interface that defines the RESTful API. The methods of this class are invoked by the code that is generated for each endpoint of the API, with parameters and return values being translated according to the rules documented in the vibe.web.rest module documentation.

A basic 'hello world' API can be defined as follows:

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

class API : APIRoot {
    override string get() { return "Hello, World"; }
}

void main()
{
    // -- Where the magic happens --
    router.registerRestInterface(new API());
    // GET http://127.0.0.1:8080/api/ and 'Hello, World' will be replied
    listenHTTP("127.0.0.1:8080", router);

    runApplication();
}

As can be seen here, the RESTful logic can be written inside the class without any concern for the actual HTTP representation.

Parameters
Detailed Description

Return value
Returning data
Template Params

Examples
See Also
Meta

Source

URLRouter registerRestInterface(URLRouter router, TImpl instance, RestInterfaceSettings settings)
URLRouter
registerRestInterface
(
TImpl
)
(
URLRouter router
,
TImpl instance
,
RestInterfaceSettings settings = null
)
URLRouter registerRestInterface(URLRouter router, TImpl instance, MethodStyle style)
URLRouter registerRestInterface(URLRouter router, TImpl instance, string url_prefix, MethodStyle style)

Parameters

router URLRouter: The HTTP router on which the interface will be registered
instance TImpl: Server instance to use
settings RestInterfaceSettings: Additional settings, such as the MethodStyle or the prefix

Detailed Description

Return value

By default, all methods that return a value send a 200 (OK) status code, or 204 if no value is being returned for the body.

Non-success: In the cases where an error code should be signaled to the user, a HTTPStatusException can be thrown from within the method. It will be turned into a JSON object that has a statusMessage field with the exception message. In case of other exception types being thrown, the status code will be set to 500 (internal server error), the statusMessage field will again contain the exception's message, and, in debug mode, an additional statusDebugMessage field will be set to the complete string representation of the exception (Exception.toString), which usually contains a stack trace useful for debugging.

Returning data

To return data, it is possible to either use the return value, which will be sent as the response body, or individual ref/out parameters can be used. The way they are represented in the response can be customized by adding @viaBody/@viaHeader annotations on the parameter declaration of the method within the interface.

In case of errors, any @viaHeader parameters are guaranteed to be set in the response, so that applications such as HTTP basic authentication can be implemented.

Template Params

TImpl = Either an interface type, or a class that derives from an interface. If the class derives from multiple interfaces, the first one will be assumed to be the API description and a warning will be issued.

Examples

This is a very limited example of REST interface features. Please refer to the "rest" project in the "examples" folder for a full overview.

All details related to HTTP are inferred from the interface declaration.

1 @path("/")
2 interface IMyAPI
3 {
4 	@safe:
5 	// GET /api/greeting
6 	@property string greeting();
7 
8 	// PUT /api/greeting
9 	@property void greeting(string text);
10 
11 	// POST /api/users
12 	@path("/users")
13 	void addNewUser(string name);
14 
15 	// GET /api/users
16 	@property string[] users();
17 
18 	// GET /api/:id/name
19 	string getName(int id);
20 
21 	// GET /some_custom_json
22 	Json getSomeCustomJson();
23 }
24 
25 // vibe.d takes care of all JSON encoding/decoding
26 // and actual API implementation can work directly
27 // with native types
28 
29 class API : IMyAPI
30 {
31 	private {
32 		string m_greeting;
33 		string[] m_users;
34 	}
35 
36 	@property string greeting() { return m_greeting; }
37 	@property void greeting(string text) { m_greeting = text; }
38 
39 	void addNewUser(string name) { m_users ~= name; }
40 
41 	@property string[] users() { return m_users; }
42 
43 	string getName(int id) { return m_users[id]; }
44 
45 	Json getSomeCustomJson()
46 	{
47 		Json ret = Json.emptyObject;
48 		ret["somefield"] = "Hello, World!";
49 		return ret;
50 	}
51 }
52 
53 // actual usage, this is usually done in app.d module
54 // constructor
55 
56 void static_this()
57 {
58 	import vibe.http.server, vibe.http.router;
59 
60 	auto router = new URLRouter;
61 	router.registerRestInterface(new API());
62 	listenHTTP(new HTTPServerSettings(), router);
63 }