Making REST requests with StreamLink
This page describes how to tunnel REST GET, POST, PUT, and DELETE operations through StreamLink to a REST endpoint, via the Liberator REST adapter.
Available from: StreamLink 8
Requires: Liberator 8
Requirements
You require:
-
StreamLink 8
-
A Caplin Platform stack running Liberator 8 with the LiberatorRESTAdapter blade activated and configured. For more information, see Activating the REST Adapter.
Overview
The StreamLink class provides four methods for interacting with REST services proxied by the Liberator REST Adapter:
| HTTP Method | StreamLink method |
|---|---|
GET |
|
POST |
|
PUT |
|
DELETE |
|
REST operations are packaged in RTTP format for transport to and from Liberator. An example request flow for a GET request is shown below:
A Liberator REST Adapter is configured to map requests to subjects beginning /EXAMPLE/… to a REST service’s base-URL:
add-rest-mapping
subject-prefix /EXAMPLE/
base-url https://www.example.com/api/v1/
end-rest-mapping
add-data-service
service-name LiberatorRESTAdapter${THIS_LEG}
service-type rest
include-pattern ^/EXAMPLE/
…
The REST service has a collection, news, available at https://www.example.com/api/v1/news. This collection is exposed to StreamLink clients as subject /EXAMPLE/news.
The sequence diagram below illustrates a StreamLink client using the StreamLink.snapshot() method to make a GET request to the REST service’s news collection:
Getting started
StreamLink’s REST methods require a StreamLink instance with a registered JSONHandler instance.
The example code below creates a JSONHandler that uses the Fast JSON Patch and Immer libraries:
var jsonHandler = {
parse: function (jsonString) {
return JSON.parse(jsonString);
},
patch: function (existingObject, jsonPatchString) {
var patch = JSON.parse(jsonPatchString);
var result = immer.produce(existingObject,
function (existing) {
return patch.reduce(jsonpatch.applyReducer, existing);
});
return result;
},
format: function(obj) {
return JSON.stringify(obj, null, "\t");
}
};Pass the JSONHandler instance to StreamLinkFactory.create to create an instance of StreamLink with a registered JSON handler:
var streamLink = caplin.streamlink.StreamLinkFactory.create({
username: "admin",
password: "admin",
liberator_urls: "rttp://localhost:18080",
json_handler: jsonHandler
});
streamLink.connect();GET requests
Use StreamLink.snapshot to send a GET request.
let subscriptionListener = {
onJsonUpdate(subscription, evt) {
console.log(evt);
},
onSubscriptionError(subscription, evt) {
},
onSubscriptionStatus(subscription, evt) {
}
};
streamLink.snapshot("/EXAMPLE/news", subscriptionListener);The SubscriptionListener.onJsonUpdate method passes in a JsonEvent object. To retrieve the JSON payload as a JavaScript object, call JsonEvent.getJSON().
If the REST method accepts parameters, append them to the subject as a querystring:
streamLink.snapshot("/EXAMPLE/news?page=2", subscriptionListener);POST requests
Use StreamLink.create to send a POST request.
let commandListener = {
onCommandError: (subject, commandErrorEvent) => {
console.log("onCommandError", subject);
},
onCommandResult: (subject, commandResultEvent) => {
console.log("onCommandResult", subject, commandResultEvent);
}
};
let payload = {
title: "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
author: "John Smith"
};
streamLink.create("/EXAMPLE/news", payload, commandListener);If the response includes a payload, call CommandResultEvent.getPayload() to retrieve it.
PUT requests
Use StreamLink.publish to send a PUT request.
let commandListener = {
onCommandError: (subject, commandErrorEvent) => {
console.log("onCommandError", subject);
},
onCommandResult: (subject, commandResultEvent) => {
console.log("onCommandResult", subject, commandResultEvent);
}
};
let payload = {
id: "63f92d0c1a3d3",
title: "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
author: "George Smith"
};
streamLink.publish("/EXAMPLE/news/63f92d0c1a3d3", payload, commandListener);If the response includes a payload, call CommandResultEvent.getPayload() to retrieve it.
DELETE requests
Use StreamLink.delete to send a DELETE request.
let commandListener = {
onCommandError: (subject, commandErrorEvent) => {
console.log("onCommandError", subject);
},
onCommandResult: (subject, commandResultEvent) => {
console.log("onCommandResult", subject, commandResultEvent);
}
};
let payload = null;
streamLink.delete("/EXAMPLE/news/63f92d0c1a3d3", payload, commandListener);If the response includes a payload, call CommandResultEvent.getPayload() to retrieve it.
See also: