{"_id":"57fcc4870312b20e00ac64e3","version":{"_id":"57fcc4860312b20e00ac64c0","project":"5435687035740020002a1c04","__v":1,"createdAt":"2016-10-11T10:52:54.637Z","releaseDate":"2016-10-11T10:52:54.637Z","categories":["57fcc4860312b20e00ac64c1","57fcc4860312b20e00ac64c2","57fcc4860312b20e00ac64c3","57fcc4860312b20e00ac64c4","57fcc4860312b20e00ac64c5","57fcc4860312b20e00ac64c6","57fcc4860312b20e00ac64c7","57fcc4860312b20e00ac64c8","57fcc4860312b20e00ac64c9","57fcc4860312b20e00ac64ca","57fcc4860312b20e00ac64cb"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"[APP-1265], [APP-1035]","version_clean":"5.2.0","version":"5.2"},"category":{"_id":"57fcc4860312b20e00ac64c8","__v":0,"version":"57fcc4860312b20e00ac64c0","project":"5435687035740020002a1c04","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-11-04T23:13:08.376Z","from_sync":false,"order":7,"slug":"lua-scripting","title":"Agent Lua Scripting"},"parentDoc":null,"__v":0,"project":"5435687035740020002a1c04","user":"5589fde775eaf50d004e4b0c","updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-11-09T19:47:35.184Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":5,"body":"Importing the `telemetry/http` library in Lua allows for you to access and retrieve data from third-party REST APIs. The `telemetry/json` library is available to decode returned JSON strings into a Lua table, or to encode Lua tables as a JSON string to submit to an endpoint.\n\n# Performing GET requests\n\nThe `get` function allows for you to make a GET request against an API endpoint. It accepts a mandatory argument containing the URL that you are querying and three optional arguments for authentication credentials and custom header values:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Name\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"`url`\",\n    \"0-1\": \"string\",\n    \"0-2\": \"The URL of the API endpoint (required).\",\n    \"2-2\": \"Password for HTTP basic auth. A `username` must be present for this field to be identified (optional).\",\n    \"1-2\": \"Username for HTTP basic auth (optional).\",\n    \"1-0\": \"`username`\",\n    \"2-0\": \"`password`\",\n    \"1-1\": \"string\",\n    \"2-1\": \"string\",\n    \"3-0\": \"`header`\",\n    \"3-1\": \"table\",\n    \"3-2\": \"A Lua table of key = value pairs. For example: `{[\\\"content-type\\\"] = \\\"application/json\\\", [\\\"accept\\\"] = \\\"application/json\\\"}` (optional).\"\n  },\n  \"cols\": 3,\n  \"rows\": 4\n}\n[/block]\nOn success, the function returns a string containing the response body. If the response is a valid JSON structure then you can use the `telemetry/json` library `decode()` function to convert the string to a Lua table. For example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"local http = require(\\\"telemetry/http\\\")\\nlocal json = require(\\\"telemetry/json\\\")\\n\\n-- Retrieve the GET response as a string\\nlocal response = http.get(\\\"https://httpbin.org/basic-auth/atestusr/secretpass\\\", \\\"atestusr\\\", \\\"secretpass\\\")\\n\\n-- Convert the JSON string to a Lua table\\nlocal table = json.decode(response)\",\n      \"language\": \"lua\"\n    }\n  ]\n}\n[/block]\n# Performing POST requests \n\nThe `post` function can be used to perform a POST request against an endpoint. It accepts the following arguments:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Name\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-2\": \"The URL of the API endpoint (required).\",\n    \"0-0\": \"`url`\",\n    \"0-1\": \"string\",\n    \"1-0\": \"`body`\",\n    \"1-1\": \"string\",\n    \"1-2\": \"An encoded string of the data to be sent to the endpoint (required).\",\n    \"2-2\": \"Username for HTTP basic auth (optional).\",\n    \"3-2\": \"Password for HTTP basic auth. A `username` must be present for this field to be identified (optional).\",\n    \"2-1\": \"string\",\n    \"3-1\": \"string\",\n    \"2-0\": \"`username`\",\n    \"3-0\": \"`password`\",\n    \"4-0\": \"`header`\",\n    \"4-1\": \"table\",\n    \"4-2\": \"A Lua table of key = value pairs. For example: `{[\\\"content-type\\\"] = \\\"application/json\\\", [\\\"accept\\\"] = \\\"application/json\\\"}` (optional).\"\n  },\n  \"cols\": 3,\n  \"rows\": 5\n}\n[/block]\nThe `telemetry/json` library `encode()` function can be used to convert a Lua table into a JSON string. For example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"local http = require(\\\"telemetry/http\\\")\\nlocal json = require(\\\"telemetry/json\\\")\\n\\n-- We can take any Lua table\\nlocal table = {title = \\\"foo\\\", body = \\\"bar\\\", userId = 1}\\n-- And convert the table into a JSON string\\nlocal js = json.encode(table)\\n\\n-- Submit an HTTP post with our JSON as the body\\nlocal result = http.post(\\\"http://jsonplaceholder.typicode.com/posts\\\", js)\\n\\n-- Write the result to the console log\\nprint(result)\",\n      \"language\": \"lua\"\n    }\n  ]\n}\n[/block]\n# Performing custom HTTP methods\n\nLua can send custom HTTP methods such as `PATCH` or `DELETE`. These are passed as the first argument to the `telemetry/json` library `custom()` function.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Name\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"`method`\",\n    \"0-1\": \"string\",\n    \"0-2\": \"The name of the HTTP method that you will use to send the request. For example `PATCH` (required).\",\n    \"1-0\": \"`url`\",\n    \"1-1\": \"string\",\n    \"1-2\": \"The URL of the API endpoint (required).\",\n    \"2-2\": \"An encoded string of the data to be sent to the endpoint. Pass an empty string `\\\"\\\"` if no body is required in the payload (required).\",\n    \"2-1\": \"string\",\n    \"2-0\": \"`body`\",\n    \"3-2\": \"Username for HTTP basic auth (optional).\",\n    \"4-2\": \"Password for HTTP basic auth. A `username` must be present for this field to be identified (optional).\",\n    \"3-1\": \"string\",\n    \"4-1\": \"string\",\n    \"3-0\": \"`username`\",\n    \"4-0\": \"`password`\",\n    \"5-2\": \"A Lua table of key = value pairs. For example: `{[\\\"content-type\\\"] = \\\"application/json\\\", [\\\"accept\\\"] = \\\"application/json\\\"}` (optional).\",\n    \"5-1\": \"table\",\n    \"5-0\": \"`header`\"\n  },\n  \"cols\": 3,\n  \"rows\": 6\n}\n[/block]\nFor example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"local http = require(\\\"telemetry/http\\\")\\nlocal json = require(\\\"telemetry/json\\\")\\n\\n-- A Telemetry number widget payload\\nlocal body = json.encode({number = {value = 93}})\\n\\n-- Example of an authenticated PATCH method\\nlocal response = http.custom(\\\"PATCH\\\", \\\"https://api.telemetrytv.com/flows/test_flow/metrics\\\", body, \\\"ad30d66583a2f35952be2af2d76f0ba20\\\", {[\\\"content-type\\\"] = \\\"application/json\\\"]})\",\n      \"language\": \"lua\"\n    }\n  ]\n}\n[/block]\n# Performing oAuth requests\n\nGET and POST requests can be made to [authenticated oAuth](doc:oauth) endpoints. The `get()` function accepts the following parameters:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Name\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"`entry_name`\",\n    \"0-1\": \"string\",\n    \"0-2\": \"The name of the authenticated oAuth entry (required).\",\n    \"1-2\": \"The URL of the API endpoint (required).\",\n    \"1-1\": \"string\",\n    \"1-0\": \"`url`\",\n    \"2-0\": \"`query_string`\",\n    \"2-1\": \"string\",\n    \"2-2\": \"A URL encoded query string to be submitted with the request (optional).\"\n  },\n  \"cols\": 3,\n  \"rows\": 3\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"local oauth = require(\\\"telemetry/oauth\\\")\\nlocal json = require(\\\"telemetry/json\\\")\\n\\n-- Retrieve the GET response as a string\\nlocal response = oauth.get(\\\"entry_name\\\", \\\"https://www.googleapis.com/analytics/v3/data/ga\\\", \\\"end-date=yesterday\\\")\\n\\n-- Convert the JSON string to a Lua table\\nlocal table = json.decode(response)\",\n      \"language\": \"lua\"\n    }\n  ]\n}\n[/block]\n`post()` works similarly but it accepts a `body` string to submit to the endpoint:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Name\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"`entry_name`\",\n    \"0-1\": \"string\",\n    \"0-2\": \"The name of the authenticated oAuth entry (required).\",\n    \"1-0\": \"`url`\",\n    \"1-1\": \"string\",\n    \"1-2\": \"The URL of the API endpoint (required).\",\n    \"2-0\": \"`body`\",\n    \"2-2\": \"An encoded string of the data to be sent to the endpoint. Pass an empty string `\\\"\\\"` if no body is required in the payload (required).\",\n    \"2-1\": \"string\",\n    \"3-2\": \"A URL encoded query string to be submitted with the request (optional).\",\n    \"3-1\": \"string\",\n    \"3-0\": \"`query_string`\"\n  },\n  \"cols\": 3,\n  \"rows\": 4\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"local oauth = require(\\\"telemetry/oauth\\\")\\nlocal json = require(\\\"telemetry/json\\\")\\n\\n-- An example payload\\nlocal body = json.encode({userId = \\\"f43rrl39cb\\\"})\\n\\n-- Send the body to the authenticated endpoint. post() returns a response table\\nlocal response = oauth.post(\\\"entry_name\\\", \\\"https://www.googleapis.com/analytics/v3/data/ga\\\", body)\",\n      \"language\": \"lua\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"accessing-third-party-apis-from-lua","type":"basic","title":"Third Party APIs"}
Importing the `telemetry/http` library in Lua allows for you to access and retrieve data from third-party REST APIs. The `telemetry/json` library is available to decode returned JSON strings into a Lua table, or to encode Lua tables as a JSON string to submit to an endpoint. # Performing GET requests The `get` function allows for you to make a GET request against an API endpoint. It accepts a mandatory argument containing the URL that you are querying and three optional arguments for authentication credentials and custom header values: [block:parameters] { "data": { "h-0": "Name", "h-1": "Type", "h-2": "Description", "0-0": "`url`", "0-1": "string", "0-2": "The URL of the API endpoint (required).", "2-2": "Password for HTTP basic auth. A `username` must be present for this field to be identified (optional).", "1-2": "Username for HTTP basic auth (optional).", "1-0": "`username`", "2-0": "`password`", "1-1": "string", "2-1": "string", "3-0": "`header`", "3-1": "table", "3-2": "A Lua table of key = value pairs. For example: `{[\"content-type\"] = \"application/json\", [\"accept\"] = \"application/json\"}` (optional)." }, "cols": 3, "rows": 4 } [/block] On success, the function returns a string containing the response body. If the response is a valid JSON structure then you can use the `telemetry/json` library `decode()` function to convert the string to a Lua table. For example: [block:code] { "codes": [ { "code": "local http = require(\"telemetry/http\")\nlocal json = require(\"telemetry/json\")\n\n-- Retrieve the GET response as a string\nlocal response = http.get(\"https://httpbin.org/basic-auth/atestusr/secretpass\", \"atestusr\", \"secretpass\")\n\n-- Convert the JSON string to a Lua table\nlocal table = json.decode(response)", "language": "lua" } ] } [/block] # Performing POST requests The `post` function can be used to perform a POST request against an endpoint. It accepts the following arguments: [block:parameters] { "data": { "h-0": "Name", "h-1": "Type", "h-2": "Description", "0-2": "The URL of the API endpoint (required).", "0-0": "`url`", "0-1": "string", "1-0": "`body`", "1-1": "string", "1-2": "An encoded string of the data to be sent to the endpoint (required).", "2-2": "Username for HTTP basic auth (optional).", "3-2": "Password for HTTP basic auth. A `username` must be present for this field to be identified (optional).", "2-1": "string", "3-1": "string", "2-0": "`username`", "3-0": "`password`", "4-0": "`header`", "4-1": "table", "4-2": "A Lua table of key = value pairs. For example: `{[\"content-type\"] = \"application/json\", [\"accept\"] = \"application/json\"}` (optional)." }, "cols": 3, "rows": 5 } [/block] The `telemetry/json` library `encode()` function can be used to convert a Lua table into a JSON string. For example: [block:code] { "codes": [ { "code": "local http = require(\"telemetry/http\")\nlocal json = require(\"telemetry/json\")\n\n-- We can take any Lua table\nlocal table = {title = \"foo\", body = \"bar\", userId = 1}\n-- And convert the table into a JSON string\nlocal js = json.encode(table)\n\n-- Submit an HTTP post with our JSON as the body\nlocal result = http.post(\"http://jsonplaceholder.typicode.com/posts\", js)\n\n-- Write the result to the console log\nprint(result)", "language": "lua" } ] } [/block] # Performing custom HTTP methods Lua can send custom HTTP methods such as `PATCH` or `DELETE`. These are passed as the first argument to the `telemetry/json` library `custom()` function. [block:parameters] { "data": { "h-0": "Name", "h-1": "Type", "h-2": "Description", "0-0": "`method`", "0-1": "string", "0-2": "The name of the HTTP method that you will use to send the request. For example `PATCH` (required).", "1-0": "`url`", "1-1": "string", "1-2": "The URL of the API endpoint (required).", "2-2": "An encoded string of the data to be sent to the endpoint. Pass an empty string `\"\"` if no body is required in the payload (required).", "2-1": "string", "2-0": "`body`", "3-2": "Username for HTTP basic auth (optional).", "4-2": "Password for HTTP basic auth. A `username` must be present for this field to be identified (optional).", "3-1": "string", "4-1": "string", "3-0": "`username`", "4-0": "`password`", "5-2": "A Lua table of key = value pairs. For example: `{[\"content-type\"] = \"application/json\", [\"accept\"] = \"application/json\"}` (optional).", "5-1": "table", "5-0": "`header`" }, "cols": 3, "rows": 6 } [/block] For example: [block:code] { "codes": [ { "code": "local http = require(\"telemetry/http\")\nlocal json = require(\"telemetry/json\")\n\n-- A Telemetry number widget payload\nlocal body = json.encode({number = {value = 93}})\n\n-- Example of an authenticated PATCH method\nlocal response = http.custom(\"PATCH\", \"https://api.telemetrytv.com/flows/test_flow/metrics\", body, \"ad30d66583a2f35952be2af2d76f0ba20\", {[\"content-type\"] = \"application/json\"]})", "language": "lua" } ] } [/block] # Performing oAuth requests GET and POST requests can be made to [authenticated oAuth](doc:oauth) endpoints. The `get()` function accepts the following parameters: [block:parameters] { "data": { "h-0": "Name", "h-1": "Type", "h-2": "Description", "0-0": "`entry_name`", "0-1": "string", "0-2": "The name of the authenticated oAuth entry (required).", "1-2": "The URL of the API endpoint (required).", "1-1": "string", "1-0": "`url`", "2-0": "`query_string`", "2-1": "string", "2-2": "A URL encoded query string to be submitted with the request (optional)." }, "cols": 3, "rows": 3 } [/block] [block:code] { "codes": [ { "code": "local oauth = require(\"telemetry/oauth\")\nlocal json = require(\"telemetry/json\")\n\n-- Retrieve the GET response as a string\nlocal response = oauth.get(\"entry_name\", \"https://www.googleapis.com/analytics/v3/data/ga\", \"end-date=yesterday\")\n\n-- Convert the JSON string to a Lua table\nlocal table = json.decode(response)", "language": "lua" } ] } [/block] `post()` works similarly but it accepts a `body` string to submit to the endpoint: [block:parameters] { "data": { "h-0": "Name", "h-1": "Type", "h-2": "Description", "0-0": "`entry_name`", "0-1": "string", "0-2": "The name of the authenticated oAuth entry (required).", "1-0": "`url`", "1-1": "string", "1-2": "The URL of the API endpoint (required).", "2-0": "`body`", "2-2": "An encoded string of the data to be sent to the endpoint. Pass an empty string `\"\"` if no body is required in the payload (required).", "2-1": "string", "3-2": "A URL encoded query string to be submitted with the request (optional).", "3-1": "string", "3-0": "`query_string`" }, "cols": 3, "rows": 4 } [/block] [block:code] { "codes": [ { "code": "local oauth = require(\"telemetry/oauth\")\nlocal json = require(\"telemetry/json\")\n\n-- An example payload\nlocal body = json.encode({userId = \"f43rrl39cb\"})\n\n-- Send the body to the authenticated endpoint. post() returns a response table\nlocal response = oauth.post(\"entry_name\", \"https://www.googleapis.com/analytics/v3/data/ga\", body)", "language": "lua" } ] } [/block]