Wiki
Clone wikilimeds-framework / Using the HttpContext
Guide: Using the HttpContext
Table of Contents
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!'; };
Updated