LimeDS features easy integration with HTTP (JSON) resources regardless of developing modules using the Java APIs or the Visual Editor and Javascript.

Java HTTP Client Library

Our Java HTTP Client Library module org.ibcn.commons.restclient comes pre-installed with all LimeDS instances as our LimeDS Core depends on it. The library exposes an OSGi service that can be used to easily call REST services with a minimal amount of code. Use the @Service annotation to obtain a reference to "org.ibcn.commons.restclient.api.Client".

The library allows expressing REST calls in a rather natural way, e.g. in order to post a JSON object to an example service, one can implement the following Segment:

@Segment
public class JsonPoster implements FunctionalSegment {

    @Service
    private Client httpClient;

    @Override
    public JsonValue apply(JsonValue... input) throws Exception {
        return httpClient.target("http://example.com/API/example").postJson(input[0].toString())
                .returnObject(Json.getDeserializer()).getBody();
    }

}

JS Compatible HTTP Client Segment

As the above Client cannot be directly used in a visual Dataflow (being an OSGi service), we've made a compatible wrapper that can be installed from our default repository: org.ibcn.limeds.httpclient

When developing in Eclipse, just drag this module from the LimeDS Main repository to the "Run Requirements" panel of your run.bndrun file. When using LimeDS standalone, you can install the module by browsing the following URL: http://localhost:8080/_limeds/installables/org.ibcn.limeds.httpclient/latest/deploy

The module exposes two Functional Segments that can be imported in your Slices:

limeds.http.Client

This Segment is actually a factory and when importing it, the LimeDS editor will prompt you to enter the URL you want to target and which method (HEAD, GET, POST, PUT, DELETE) you want to use. You can supply JSON as a HTTP request by supplying it as an input argument to the client's apply function. The return value represents the HTTP response body parsed as a JSON value. The following example we'll perform a query-by-example on a remote HTTP API using the client instance (configured to perform a POST on a /users/query endpoint):

var apply = function(input) {
  var query = {
    lastname = "Doe"
    accountType = "user",
  };
  return httpClient.apply(query);
};

limeds.http.AdvancedClient

In some cases the above basic Client Segment will not suffice, e.g. when you want to specify request headers, or use a content-type different from JSON. For this purpose we've added an AdvancedClient that can also be imported in your Slices.

This function takes as argument a Request Context JSON object and an optional JSON request body. The context object is structured as follows:

{
    "method" : "String [HEAD, GET, PUT, POST, DELETE] (The HTTP method for the request.)",
    "targetUrl" : "String (The target URL for the request.)",
    "headers" : {
        "@typeInfo" : "Object * (The HTTP headers for the request.)"
    },
    "body" : "String * (String representation of the body that is sent with the request with the content-type specified using headers. For JSON bodies, ommit this attribute and submit the JSON body as a second argument for the apply function.)"
}

The return value of the function is a JSON response object, structured as follows:

{
    "headers" : {
        "@typeInfo" : "Object (The HTTP headers for the response.)"
    },
    "status" : "IntNumber (The status code of the response.)",
    "body" : "Any (The response body, parsed as JSON if the content-type is application/json, otherwise represented as a String.)"
}

To demonstrate the usage of the AdvancedClient we revisit the previous example, but add a request header that indicates the API version to use:

var apply = function(input) {
  var query = {
    lastname = "Doe"
    accountType = "user",
  };
  var requestContext = {
    method: "POST",
    targetUrl: "http://somehost/users/query",
    headers: {
      apiVersion: 1.3
    }
  };
  return httpClient.apply(requestContext, query).body;
};