Liberator REST client interface

Liberator’s HTTP and HTTPS interfaces now support REST calls to Caplin Platform data, including onward REST endpoints proxied by Liberator’s REST Adapter.

Available from: Liberator 8

Enabling the REST client interface

REST support in Liberator’s HTTP and HTTPS interfaces is disabled by default.

To enable REST client support support, set the Liberator configuration item http-rest-path to a URI prefix that identifies URLs to be handled by the HTTP interface’s REST handler.

The REST handler strips the http-rest-path prefix from the URI and treats the remainder of the URI as a subject, which it serves according to the Liberator’s configured data service routing. Both subjects routed to DataSources and subjects routed to onward REST endpoints via Liberator’s REST Adapter are supported.

Example 1. Enabling the REST client interface

In this example, we configure Liberator’s HTTP and HTTPS interfaces to serve all URLs beginning /REST using the REST handler.

rttpd.conf
http-rest-path /REST

Authentication

All requests to Liberator’s REST client interface must authenticate with Liberator using the X-Liberator-Authorization header.

REST requests for subjects that proxy remote REST endpoints may include additional authentication headers, including the HTTP standard Authorization header, for authentication with the remote REST endpoint. Liberator forwards a subset of the original request headers to the REST Adapter for inclusion in the proxied request.

Header specification
X-Liberator-Authorization

[Required] Authenticate with the Liberator REST client interface. This header has the same syntax as the standard HTTP Authorization header and supports the Basic authentication scheme. If your deployment uses Caplin KeyMaster authentication, then you can specify a KeyMaster token in place of a password.

This header is only recognised by the handler for Liberator’s REST client interface.

Example use of X-Liberator-Authorization
X-Liberator-Authorization: Basic YWRtaW46YWRtaW4=
Example 2. A GET request for a Caplin Platform record

In this example, a REST client submits a GET request for a snapshot of subject /FX/EURUSD, a Type 1 Record served by a Caplin Platform DataSource.

The Liberator’s REST client interface has been enabled and handles all requests for subjects prefixed with /REST (see http-rest-path).

The REST client’s first request is unauthenticated and Liberator’s REST client interface returns an HTTP status code of 403 (forbidden).

The REST client’s second request includes the X-Liberator-Authorization header. If Liberator accepts the credentials, it strips the http-rest-path prefix from the subject and applies standard authorization checks and data-routing rules for the subject request. As with all snapshot (non-streaming) requests, Liberator discards the data once it has been served to the client.

HTTP ClientLiberatorAdapter for /FXcurl--request GET--url "http://localhost:18080/REST/FX/EURUSD"GET/REST/FX/EURUSDHTTP/1.1 403 Forbiddencurl--request GET--header "X-Liberator-Authorization: Basic YWRtaW46YWRtaW4="--url "http://localhost:18080/REST/FX/EURUSD"GET/REST/FX/EURUSDX-Liberator-Authorization: Basic YWRtaW46YWRtaW4=Request /FX/EURUSD
Example 3. A GET request for a subject that proxies a remote REST endpoint

In this example, a REST client submits a GET request for /REST/FOOBAR/widgets. The /FOOBAR namespace proxies a remote REST endpoint, foobar.example.com/api. The proxy process is invisible to the client and is handled by Liberator in conjunction with Liberator’s REST Adapter.

The remote REST endpoint, foobar.example.com/api, requires HTTP Basic Authentication.

The Liberator’s REST interface has been enabled and handles all requests for subjects prefixed with /REST (see http-rest-path).

The Liberator’s REST Adapter has been activated and is configured to proxy the /FOOBAR namespace to the remote REST endpoint, foobar.example.com/api.

The REST client’s first request is unauthenticated and Liberator’s REST client interface returns an HTTP status code of 403 (forbidden).

The REST client’s second request includes two authentication headers:

  • X-Liberator-Authorization to authenticate with Liberator

  • Authorization to authenticate with foobar.example.com/api

If Liberator accepts the credentials provided in X-Liberator-Authorization, it strips the http-rest-path prefix from the subject and applies standard authorization checks and data-routing rules for the subject request. In this case, the subject routes to the REST Adapter, and Liberator includes a subset of the client’s HTTP request headers in its data request to the REST Adapter.

The REST Adapter receives the request and proxies it to foobar.example.com/api, including the subset of the original request headers forwarded by Liberator.

As with all snapshot (non-streaming) requests, Liberator discards the data once it has been served to the client.

HTTP ClientLiberatorREST AdapterREST Serverfoobar.example.comcurl--request GET--url "http://localhost:18080/REST/FOOBAR/WIDGETS"GET/REST/FOOBAR/widgetsHTTP/1.1 403 Forbiddencurl--request GET--header "X-Liberator-Authorization: Basic YWRtaW46YWRtaW4="--header "Authorization: Basic dXNlcjE6cGFzc3dvcmQxMjM0"--url "http://localhost:18080/REST/FX/EURUSD"GET/REST/FOOBAR/widgetsX-Liberator-Authorization: Basic YWRtaW46YWRtaW4=Authorization: Basic dXNlcjE6cGFzc3dvcmQxMjM0Map /FOOBAR/widgetsto foobar.example.com/api/widgetsGET/api/widgetsAuthorization: Basic dXNlcjE6cGFzc3dvcmQxMjM0

HTTP header forwarding

When a REST request is made to a subject that proxies a remote REST endpoint, Liberator forwards a subset of request headers to the REST Adapter and returns a subset of response headers to the client.

All headers are faithfully forwarded, with the exception of the following headers which are suppressed:

Request headers not forwarded to the REST Adapter

  • Connection

  • Keep-Alive

  • Upgrade

  • Transfer-Encoding

  • TE

  • Proxy-Authorization

  • Host

  • Forwarded

  • X-Forwarded-For

  • X-Forwarded-Host

  • X-Forwarded-Proto

  • Cookie

Response headers not returned from the REST Adapter

  • Connection

  • Keep-Alive

  • Upgrade

  • Transfer-Encoding

  • Proxy-Authenticate

  • Alt-Svc

  • Strict-Transport-Security

  • Set-Cookie

  • Set-Cookie2

REST calls to Platform data

You can make REST calls to subjects provided by Caplin Platform DataSources.

LiberatorHTTP ClientHTTP/HTTPSAdapter for /FXGET/REST/FX/EURUSDRequest /FX/EURUSDbid: 1.15294ask: 1.15455HTTP/1.1 200 OKContent-Type: application/json {"subject": "/FX/EURUSD","type": "map","status": "UNKNOWN","data": {"bid": "1.15294","ask": "1.15455"}}
GET request for Platform data
GET <http-rest-path><subject>

Requests a snapshot of a Caplin Platform subject.

Response
200 OK

Returns the subject’s data enclosed in a JSON envelope.

Response format
{
  "subject": "<requested_subject>",
  "type": "<map|object|container>",
  "status": "<OK|STALE|UNKNOWN>",
  "data": ...
}
Response example: record
{
  "subject":"/EXAMPLES/PRICING/TYPE1/AAPL",
  "type":"map",
  "status":"OK",
  "data":{
    "Time":"09:18:57",
    "FullName":"Apple Inc.",
    "BestBid":"661.132",
    "BestAsk":"688.116",
    "Last":"674.624",
    "NetChange":"10.624"
  }
}
Response example: container
{
  "subject":"/EXAMPLES/PRICING/CONTAINERS/EQUITIES",
  "type":"container",
  "status":"OK",
  "data":[
    {
      "subject":"/EXAMPLES/PRICING/TYPE1/AAPL",
      "type":"map",
      "status":"OK",
      "data":{
        "Time":"09:18:57",
        "FullName":"Apple Inc.",
        "BestBid":"661.132",
        "BestAsk":"688.116",
        "Last":"674.624",
        "NetChange":"10.624"
      }
    },
    ...
  ]
}
404 Not Found

Subject unknown or temporarily unavailable

Examples
Requesting /SYSTEM/INFO
curl --request GET \
  --user admin:admin \
  --url 'http://localhost:18080/REST/SYSTEM/INFO'
POST <http-rest-path><subject>

Upload (contribute) a payload to a Caplin Platform subject.

For REST calls to Caplin Platform subjects, the REST handler does not make a distinction between POST and PUT. Both methods may be used interchangeably.

Payload

Choose the payload type according to the data type of the subject you are contributing data to.

Caplin Platform records

Submit a payload of type application/x-www-form-urlencoded

Caplin Platform generic objects

Submit a payload of type application/x-www-form-urlencoded

Caplin Platform JSON objects

Submit a payload of type application/json

Response
200 OK

Data contributed successfully. This response does not include a payload.

404 Not found

Subject unknown or temporarily unavailable.

Examples
Contributing data to a Caplin Platform record
curl --request POST \
  --user admin:admin \
  --data 'name=foo' \
  --url 'http://localhost:18080/REST/MY_SUBJECT'
Contributing data to a Caplin Platform JSON object
curl --request POST \
  --user admin:admin \
  --header "Content-Type: application/json" \
  --data '{"name": "foo"}' \
  --url 'http://localhost:18080/REST/MY_SUBJECT'
PUT <http-rest-path><subject>

See POST above.

Errors

All errors are returned in HTML format.

For example, if a data service’s DataSource is down, Liberator returns the following 404 message:

<HTML>

<HEAD>
	<TITLE>404 Not Found</TITLE>
</HEAD>

<BODY>
	<H1>Not Found</H1>
	The requested URL [url] was not found on this server.<P>
</BODY>

</HTML>

REST calls to onward REST endpoints

You can make REST calls to an onward REST endpoint proxied by Liberator’s REST Adapter.

Configuration for the deployment in the diagram below
global_config/overrides/servers/Liberator/etc/rttpd.conf
http-rest-path /REST
global_config/overrides/LiberatorRESTAdapter/DataSource/etc/datasource.conf
add-rest-mapping
    subject-prefix /FOOBAR/
    base-url https://foobar.example.com/api/
end-rest-mapping
global_config/overrides/LiberatorRESTAdapter/Liberator/etc/rttpd.conf
add-data-service
    service-name LiberatorRESTAdapter${THIS_LEG}
    service-type rest
    include-pattern "^/FOOBAR/"
    ...
end-data-service
LiberatorHTTP ClientHTTP/HTTPSREST AdapterREST Serverfoobar.example.comGET/REST/FOOBAR/widgetsRequest /FOOBAR/widgetsGET/api/widgetsHTTP/1.1 200 OKContent-Type: application/json [{"id": "1", ...},{"id": "2", ...},...]HTTP/1.1 200 OKContent-Type: application/json [{"id": "1", ...},{"id": "2", ...},...]
GET request to a proxied REST endpoint
GET <http-rest-path><subject-prefix><uri>

Request a REST resource.

For details of attributes, headers, and expected responses, refer to the specification of the onward REST endpoint.

Examples
Request a list of widgets
curl --request GET \
  --user admin:admin \
  --url 'http://localhost:18080/REST/FOOBAR/widgets'
POST <http-rest-path><subject-prefix><uri>

Create a REST resource.

For details of attributes, headers, and expected responses, refer to the specification of the onward REST endpoint.

Examples
Create a widget
curl --request POST \
  --user admin:admin \
  --header "Content-Type: application/json" \
  --data '{"name": "Advanced Widget"}' \
  --url 'http://localhost:18080/REST/FOOBAR/widgets'
PUT <http-rest-path><subject-prefix><uri>

Update a REST resource.

For details of attributes, headers, and expected responses, refer to the specification of the onward REST endpoint.

Examples
Update a widget
curl --request PUT \
  --user admin:admin \
  --header "Content-Type: application/json" \
  --data '{"name": "Express Widget"}' \
  --url 'http://localhost:18080/REST/FOOBAR/widgets/1'
DELETE <http-rest-path><subject-prefix><uri>

Delete a REST resource.

For details of attributes, headers, and expected responses, refer to the specification of the onward REST endpoint.

Examples
Delete a widget
curl --request DELETE \
  --user admin:admin \
  --url 'http://localhost:18080/REST/FOOBAR/widgets/1'

Errors

If the REST Adapter receives an error from the REST endpoint, the REST Adapter returns the endpoint’s response to the HTTP client.

If the REST Adapter cannot connect to the REST endpoint, the REST Adapter returns the following JSON payload to the HTTP client:

{
  "code": "500",
  "payload": {
    "message":"Error servicing HTTP request."
  }
}

If the REST Adapter is down, Liberator returns the following HTML to the HTTP client:

<HTML>

<HEAD>
	<TITLE>404 Not Found</TITLE>
</HEAD>

<BODY>
	<H1>Not Found</H1>
	The requested URL ... was not found on this server.<P>
</BODY>

</HTML>