{"__v":22,"_id":"572410f3eae5090e00ee6236","category":{"__v":0,"_id":"5723f854110e570e00486c7a","project":"5723ead0fda3c70e005b88e5","version":"5723eaebeae5090e00ee61f1","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-04-30T00:12:04.115Z","from_sync":false,"order":2,"slug":"http-api","title":"Reference"},"parentDoc":null,"project":"5723ead0fda3c70e005b88e5","user":"5723ea8efda3c70e005b88e3","version":{"__v":3,"_id":"5723eaebeae5090e00ee61f1","project":"5723ead0fda3c70e005b88e5","createdAt":"2016-04-29T23:14:51.190Z","releaseDate":"2016-04-29T23:14:51.190Z","categories":["5723eaebeae5090e00ee61f2","5723f854110e570e00486c7a","572a28f6d10a200e00b1cb14"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"0.1.0","version":"0.1"},"updates":["57899d20f55bf80e00d0c346"],"next":{"pages":[],"description":""},"createdAt":"2016-04-30T01:57:07.621Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"Lever's HTTP API is based solely on **POST** requests that invoke Lever methods.\n\n# :arrow-right: HTTP POST\nThe general form of the HTTP endpoint URL is\n\n`http[s]://<environment>/<service>[/<resource>]/<method>`\n\nor\n\n`http[s]://<host>:<port>/<service>[/<resource>]/<method>?forceenv=<environment>`\n\nWhere\n\n* **<environment>** is the Lever environment.\n* **<service>** is the Lever service name.\n* **<resource>** *(optional)* is the Lever resource name (if any).\n* **<method>** is the name of the method to be invoked.\n\nThe 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).\n\n### Invoking regular (non-streaming) methods\n\nFor 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.\n\n```json\n[\"this is the first arg\", {\"this\": \"is\", \"the\": \"second arg\"}, 3.0, false, \"last arg\"]\n```\n\nSimilarly, **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\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"module.exports.myMethod = function (callback) {\\n  callback(null, {\\\"this\\\": \\\"is\\\", \\\"a\\\": \\\"response\\\"});\\n};\",\n      \"language\": \"javascript\",\n      \"name\": \"service.js\"\n    }\n  ]\n}\n[/block]\n... will return\n\n```json\n{\"this\":\"is\",\"a\":\"response\"}\n```\n\n### Invoking streaming methods\n\nFor 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.\n\nThe 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.\n\nStreaming methods with byte args are not yet supported as part of the HTTP API.\n\nThe 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`.\n\nNote 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.\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"Important\",\n  \"body\": \"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.\\n\\nThis 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.\"\n}\n[/block]","excerpt":"This page will introduce you to the HTTP API of Lever","slug":"http-api","type":"basic","title":"HTTP API"}

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. # :arrow-right: 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 * **<environment>** is the Lever environment. * **<service>** is the Lever service name. * **<resource>** *(optional)* is the Lever resource name (if any). * **<method>** 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 [block:code] { "codes": [ { "code": "module.exports.myMethod = function (callback) {\n callback(null, {\"this\": \"is\", \"a\": \"response\"});\n};", "language": "javascript", "name": "service.js" } ] } [/block] ... 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. [block:callout] { "type": "danger", "title": "Important", "body": "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.\n\nThis 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." } [/block]