Guide: Using the HttpContext

Table of Contents

Guide: Using the HttpContext
Introduction
HttpContext format
Usage Examples

Introduction

Each FunctionalSegment can be exposed as an HTTP endpoint:

For Java Segments this is done by adding the @HttpOperation annotation
For non-Java Segments this can be done using the visual editor

It is important to note that configuring a HTTP endpoint doesn't prevent the Segment from being called from other Segments. However, when the Segment does get triggered from the configured HTTP endpoint, LimeDS makes sure that a HttpContext object is injected as the second argument of the Segment.

HttpContext format

The HttpContext object is a regular JSON object that is structured as follows:

{
  "request" : {
    "headers" : {
      //A mapping of the HTTP headers present for this request
    },
    "query" : {
      //A mapping of the URL query parameters for this request
    },
    "path" : {
      //A mapping of the path parameters for this request
    },
    "auth" : {
      //The injected authentication information for this request (optional)
    }
  },
  "response" : {
    "headers" : {
      //Use this mapping to set the HTTP response headers
    },
    "status" : //Use this attribute to set the HTTP response code
  }
}

Note that authentication information will obviously be only available if authentication or authorization is configured for the segment.

Usage Examples

Using query parameters (Java)

E.g. when exposing some kind of management interface and we need to setup a HTTP GET method with an optional filter query parameter, we could write the following Java FunctionalSegment:

@Segment
public class HttpExample implements FunctionalSegment {

  @Service
  private SomeManager manager;

  @HttpOperation(method=HttpMethod.GET, path="/manager/list")
  public JsonValue apply(JsonValue... input) {
     JsonObject request = input[1].get("request").asObject();
     if(request.get("query").has("filter")) {
       return manager.getFilteredRecords(request.get("query").getString("filter"));
     } else {
       return manager.getAllRecords();
     }
  }

}

Alternatively, LimeDS provides an abstract HttpEndpointSegment class that allows a more streamlined implementation:

@Segment
public class HttpExample extends HttpEndpointSegment {

  @Service
  private SomeManager manager;

  @HttpOperation(method=HttpMethod.GET, path="/manager/list")
  public JsonValue apply(JsonValue body, HttpContext context) {
     if(context.queryParameters().has("filter")) {
       return manager.getFilteredRecords(context.queryParameters().getString("filter"));
     } else {
       return manager.getAllRecords();
     }
  }

}

Using query parameters (Javascript)

E.g. when exposing some kind of management interface and we need to setup a HTTP GET method with an optional filter query parameter, we could write the following Javascript Segment:

var apply = function(input, httpContext) {
  if(httpContext.request.query.filter) {
    return manager.apply({
      operation: 'filter',
      filter: httpContext.request.query.filter
    });
  } else {
    return manager.apply({
      operation: 'list'
    });
  }
};

Setting response headers (Java)

E.g. We can set a cookie using a Java Segment as follows:

@Segment
public class HttpExample extends HttpEndpointSegment {

  @HttpOperation(method=HttpMethod.GET, path="/cookieExample")
  public JsonValue apply(JsonValue body, HttpContext context) {
    context.respondWith("Set-Cookie", "message=Hello!");
    return null;
  }

}

Setting response headers (Javascript)

E.g. We can set a cookie using a Javascript Segment as follows:

var apply = function(input, httpContext) {
  httpContext.response.headers['Set-Cookie'] = 'message=Hello!';
};

Wiki

limeds-framework / Using the HttpContext