HTTP API

This page will introduce you to the HTTP API of Lever

Lever's HTTP API is based solely on POST requests that invoke Lever methods.

➡️ HTTP POST

The general form of the HTTP endpoint URL is

http[s]://<environment>/<service>[/<resource>]/<method>

or

http[s]://<host>:<port>/<service>[/<resource>]/<method>?forceenv=<environment>

Where

• is the Lever environment.
• is the Lever service name.
• (optional) is the Lever resource name (if any).
• is the name of the method to be invoked.

The second form is useful when running Lever in development where the server's hostname might not be the same as the environment, or the server might not be listening on port 80 (HTTP) or 443 (HTTPS).

Invoking regular (non-streaming) methods

For regular methods, the body of the request can be either JSON (if the method takes JSON args) or binary data (it the methods takes a single, byte arg). The Content-Type needs to be set appropriately as application/json or application/octet-stream respectively. Below is an example where the args are JSON.

JSON

["this is the first arg", {"this": "is", "the": "second arg"}, 3.0, false, "last arg"]

Similarly, the response will have the Content-Type either application/json or application/octet-stream, depending of the data type returned by the Lever method invoked. As an example, an invokation of the method

service.js

module.exports.myMethod = function (callback) {
  callback(null, {"this": "is", "a": "response"});
};

... will return

JSON

{"this":"is","a":"response"}

Invoking streaming methods

For streaming methods, both the request body and the response will be split in multiple consecutive messages. This makes it possible for the client and the service to have a full-duplex conversation during the invokation of the method.

The first line of the request body will be assumed to be the JSON args, regardless of the Content-Type. The rest of the request's message body will be interpreted depending of Content-Type. If Content-Type is application/json then each line of the body is interpreted as individual JSON messages. If Content-Type is application/octet-stream, then the body is split into chunks arbitrarily and each chunk represents an individual message of type bytes. Do not assume that the chunks are split the same way they are sent. Mixed JSON and byte messages as part of a single method invokation are not yet supported as part of the HTTP API.

Streaming methods with byte args are not yet supported as part of the HTTP API.

The format of the response of streaming methods is similar to the request's body. If the server sends JSON messages, then each message will be presented JSON, one per line in the response and the Content-Type will be set to application/json. If the server sends byte message, then messages will be concatenated as part of the response and the Content-Type will be set to application/octet-stream.

Note that in the case of streaming methods, the request and the response can be written and read in parallel, message by message, thus being able to create a more complex negotiation as part of a single method invokation.

❗️

Important

Long-lived connections are not supported by the HTTP API. It is assumed that even streaming method invokations end within 30 seconds. This is because there is no guarantee that a proxy between the client and the server will allow connections to stay up longer than this.

This means that streaming methods used for the purpose of push notifications can only be achieved from a client library (and not via the HTTP API). And currently the node client library does not work in the browser. We are currently working on a websocket-based gateway and a client library compatible with browsers to cover this use case.