HTTP endpoint

Overview

You can send single events or stream data to your Devo domain over HTTP. Generate a token for your HTTP endpoint in the Devo web application, then use that token to set up event sending from your HTTP endpoint.

Maximum file size

Note that there’s a limit of 32 MB when you use this sending method.

Create the token needed to authorize the endpoint

The OAuth token is a 32-character alphanumeric string that authorizes a connection to Devo. When this token is used when making HTTP requests to Devo, it is recognized by the platform and the connection is authorized and the request is carried out. To create the required token:

Configure the HTTP endpoint

Once the token has been generated, you can configure the endpoint. The URL to send the HTTP request follows this format:

<endpoint>/<mode>/<domain>/token!<token>/<host>/<tag>?<message>

Where each element in the URL is described below:

Element	Description
`<endpoint>` USA: `https://http-us.devo.io:443` Europe: `https://http-eu.devo.io` Canada: `https://http-ca.devo.io:443` Asia-Pacific (APAC): `https://collector-ap.devo.io:8443` (The endpoint will be different depending on the ingestion source. Currently we have `collector-ap` for Singapore and `collector-ap2` for Sydney)	Use the endpoint that corresponds to the Devo Cloud region you use.
`<mode>`	This can be one of the following: `event` - Use this mode to send single events. `GET` and `POST` methods are accepted. `stream` - Use this mode to send multiple events. Only `POST` is accepted. Use the header `Content-Encoding: gzip` to send multiple compressed events in your request body. Check an example in the section below.
`<domain>`	The name of the Devo domain where the events are being sent to.
`<token>`	The token you generated in Devo to authorize your connection.
`<host>`	Specify the required hostname.
`<tag>`	The Devo tag to be applied to the events. Learn more about tags in About Devo tags.
`<message>`	The log to be sent. Note that this is only valid if you’re using the `event` mode, that is to say, you're sending a single event to Devo. In this case, the event is added to the query string. In case of a `POST` request in `stream` mode, events should be added to the request body. See some examples of this in the section below.

Here is an example of an endpoint URL:

https://http-us.devo.io/event/myDomain/token!a5370g9e8f7d7edf9d/local1/my.app.http.js?this%20is%20a%20example%20of%20log

Code samples

Here you can see a few examples of how token-based HTTP requests can be sent from an endpoint to a table (or tables) in a Devo domain.

Python - Sending a single event

import requests
from urllib.parse import quote
devo_endpoint="http://devoEndpoint"
domain="demoDomain"
token="example_token_1234abcd"
hostname="my_src_hostname"
devo_table="my.app.demo.send"
message = quote("test event")
url = f'{devo_endpoint}/event/{domain}/token!{token}/{hostname}/{devo_table}?{message}'
payload={}
headers = {}
requests.request("GET", url, headers=headers, data=payload)

Python - Sending a file with events

import requests
with open('filePath', 'rb') as f:
  data = f.read()
devo_endpoint="http://devoEndpoint"
domain="demoDomain"
token="example_token_1234abcd"
hostname="my_src_hostname"
devo_table="my.app.demo.send"
url = f'{devo_endpoint}/stream/{domain}/token!{token}/{hostname}/{devo_table}'
requests.request("POST", url, data=data)

Java

package lt.example.http.send;

import java.io.IOException;
import java.io.UnsupportedEncodingException;
import java.net.HttpURLConnection;
import java.net.URL;
import java.net.URLEncoder;

public class Main {
  // /event/<identity>/token!<signature>/<host>/<tag>?<message>

  public static void main(String[] args) {
    try {
      final String url = generateUrl(
        "http://devoEndpoint",
        "demoDomain",
        "example_token_1234abcd",
        "my_src_hostname",
        "my.app.demo.send",
        encodeToHttp("example_of_log"));

      URL obj = new URL(url);
      HttpURLConnection con = (HttpURLConnection) obj.openConnection();
      con.setRequestMethod("GET");
      int responseCode = con.getResponseCode();
      System.out.println("Response Code : " + responseCode);
      System.out.println("Response: " + con.getResponseMessage());
    } catch (UnsupportedEncodingException e) {
      System.err.println("Cannot encode message: " + e.getMessage());
      e.printStackTrace();
    } catch (IOException e) {
      System.err.println(e.getMessage());
      e.printStackTrace();
    }
  }

  public static String encodeToHttp(String str)
    throws UnsupportedEncodingException {
    return URLEncoder.encode(str, "UTF-8").replace("+","%20");
  }

  public static String generateUrl(String serverPath, String domain,
                                   String token, String hostname,
                                   String tag, String msg) {

    return new StringBuilder(serverPath)
            .append("/event/")
            .append(domain).append("/token!")
            .append(token).append("/")
            .append(hostname).append("/")
            .append(tag).append("?")
            .append(msg)
            .toString();
  }
}

Java (POST example)

import java.io.IOException;
import java.io.UnsupportedEncodingException;
import java.net.HttpURLConnection;
import java.net.URL;
import java.io.DataOutputStream;

public class Main {
    public static void  main(String[] args) {
        try{
            final String url = generateUrl(
                    "http://devoEndpoint",
                    "demoDomain",
                    "example_token_1234abcd",
                    "my_src_hostname",
                    "my.app.demo.send");

            URL obj = new URL(url);
            HttpURLConnection con = (HttpURLConnection) obj.openConnection();
            con.setRequestMethod("POST");
            con.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
            con.setRequestProperty("charset", "utf-8");
            con.setDoOutput(true);
            
            String urlParameters;
            DataOutputStream wr = new DataOutputStream(con.getOutputStream());
            
            for (int i = 0; i < 3; i++) {
                urlParameters = "PostExample" + i + "\n"; // \n needed to send multiple events, otherwise the stream will be sent as a single event
                wr.writeBytes(urlParameters);
            }

            wr.flush();
            wr.close();
            int responseCode = con.getResponseCode();
            System.out.println("Response Code : " + responseCode);
            System.out.println("Response: " + con.getResponseMessage());

        } catch (UnsupportedEncodingException e) {
            System.err.println("Cannot encode message: " + e.getMessage());
            e.printStackTrace();
        } catch (IOException e) {
            System.err.println(e.getMessage());
            e.printStackTrace();
        }
    }

    public static String generateUrl(String serverPath, String domain,
                                     String token, String hostname,
                                     String tag) {

        return new StringBuilder(serverPath)
                .append("/stream/")
                .append(domain).append("/token!")
                .append(token).append("/")
                .append(hostname).append("/")
                .append(tag).append("?")
                .toString();
    }
}

HTML - jQuery

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Devo: JQuery Example</title>
  <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.2.1/jquery.min.js"></script>
  <script>
    var serverPath = "http://devoEndpoint";
    var domain = "demoDomain";
    var token = "example_token_1234abcd";
    var hostname = "my_src_hostname";
    var tag = "my.app.demo.send";
    var msg = "this is a example of log";

    function generateUrl(domain, token, hostname, tag, msg) {
      return serverPath + "/event/" + domain + "/token!" + token + "/" +
        hostname + "/" + tag + "?" + msg;
    }

    $(document).ready(function() {
      $.get(generateUrl(domain, token, hostname, tag, msg),
        function(data, status) {
          alert("Data: " + data + "\nStatus: " + status);
        });
    });
  </script>
</head>
<body>
  <h1>JQuery Example</h1>
</body>
</html>

HTML - JavaScript

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Devo: JavaScript Example</title>
  <script>
    var serverPath = "http://devoEndpoint";
    var domain = "demoDomain";
    var token = "example_token_1234abcd";
    var hostname = "my_src_hostname";
    var tag = "my.app.demo.send";
    var msg = "this is a example of log";

    function generateUrl(domain, token, hostname, tag, msg) {
      return serverPath + "/event/" + domain + "/token!" + token + "/" +
        hostname + "/" + tag + "?" + msg;
    }

    var req;

    if (window.XMLHttpRequest) {
      req = new XMLHttpRequest();
    } else if (window.ActiveXObject) {
      try {
        req = new ActiveXObject("Msxml2.XMLHTTP");
      } catch (e) {

        try {
          req = new ActiveXObject("Microsoft.XMLHTTP");
        } catch (e) {}
      }
    }

    req.open("GET", generateUrl(domain, token, hostname, tag, msg), true);
    req.send(null);
  </script>
</head>
<body>
  <h1>JS Example</h1>
</body>
</html>

cURL - Sending a single event

curl -v ‘<DEVO_ENDPOINT>/event/<DOMAIN>/token!<TOKEN>/<HOSTNAME>/<TAG>?this%20is%20a%20example%20of%20log’

cURL - Sending a file with events

curl -v --request POST --url '<DEVO_ENDPOINT>/stream/<DOMAIN>/token!<TOKEN>/<HOSTNAME>/<TAG>' --header 'Content-Type:application/x-www-form-urlencoded' --header 'charset:utf-8' --data-binary @<FILE_PATH>

cURL - Sending a file with compressed events

curl -v --request POST --url '<DEVO_ENDPOINT>/stream/<DOMAIN>/token!<TOKEN>/<HOSTNAME>/<TAG>' --header 'Content-Encoding: gzip' --data-binary @<FILE_PATH>

Response codes

Take into consideration the following points related to the response codes returned by the HTTP API:

The HTTP API is designed as an asynchronous API that immediately returns a 2XX status code upon receiving a request.
The 2XX status code of the response only indicates that the request has been received but not completed yet.
The response is sent prior to any further processing, including token validation (authentication and authorization), or any other checks that may result in an invalid event submission.
The specific 2xx status code depends on the mode of the request. The /event mode returns a 204 No Content status code while the /stream mode returns a 200 OK
The only way to verify that an event is properly stored is by querying it.
This HTTP API operates similarly to job submissions commonly used in batch-processing scenarios.