Home

If you want to create a REST service in Dirigible, you will need aRESTme. It will enable you to configure HTTP endpoints and handlers that will service them without all the boilerplate around this.

The key component in arestme is the http module (arestme/http). It provides all the basic functionality to create HTTP services however you like to design them. Another component called data_service (arestme/data_service) leverages http and introduces bindings between certain HTTP requests and data access objects with functions that can handle them. It introduces a standard protocol and design for a data service and removes the boilerplate around creating one. Think of it somewhat as of the distant cousin of OData.

The simplest HTTP service that you can create with aRESTme looks like this:

require('arestme/http').get().service();

Congratulations! You've got a service now. If you save this code in a file myservice.js in a Dirigible project's ScriptingServices section, you can request it as HTTP resource: GET /js/myservice.js and it will service your request. Check Dirigible's console (if you use the Web IDE look for Log Console or if running locally check the server's console). When you send a request you will see the following printed for you:

[arestme/HttpController] No suitable resource handler for resource [myservice.js], Verb[GET], Content-Type[], Accept["text/html", "application/xhtml+xml", "application/xml", "image/webp", "*/*"] found

Headers can vary, depending on what agent you used, but the important part now is the message in this log. Despite being functional this service is not very useful without handlers for requests to it. We need to instruct it how to behave upon different requests.

Suppose you want to send request GET /js/myservice/js and receive response with status code 200 and body payload "OK". Here is how you need to change myservice.js to achieve this:

require('arestme/http').get()
.addResourceHandler("","get", function(ctx, io){
    io.response.println('OK');
}).service();

A quick look at the console after requesting the service now looks something like this:

[arestme/HttpController] Serving request for resource [myservice.js], Verb[GET], Content-Type[], Accept["text/html", "application/xhtml+xml", "application/xml", "image/webp", "*/*"] finished

We've just made our first functional HTTP service!

Now, if you wanted to add one more endpoint path to the myservice.js resource that is not static and print the dynamic parts of its URL template when requested with GET verb, this would look like this:

require('arestme/http').get()
.addResourceHandler("","get", function(ctx, io){
    io.response.println('OK');
})
.addResourceHandler("{part1}/part2/{part3}","get", function(ctx, io){
    io.response.println('part1: ' + ctx.pathParams.part1 + ', part3: ' + ctx.pathParams.part3);
}).service();

If you request the service with: js/myservice.js/abc/part2/123 you will now receive payload: part1: abc, part3: 123 Note, how the resource path variables got resolved to the concrete values from the request and have been made available to the handler function to print to the output stream.