Document toolboxDocument toolbox

HTTP endpoint

Owned by Juan Tomás Alonso Nieto (Deactivated)
Last updated: Dec 08, 2024 by Julio Vargas
9 min read
[ 1 Overview ] [ 2 Create the token needed to authorize the endpoint ] [ 3 Configure the HTTP endpoint ] [ 4 Code samples ] [ 5 Response codes ]

Overview

The recommended way to send events to Devo is by using Syslog. However, there are situations where HTTP ingestion may be preferred, such as when direct TCP connections are not feasible or when clients need to integrate with systems that only support HTTP.

Devo offers two HTTP endpoints or modes for event ingestion:

  • Event mode - Designed to send one event per HTTP request.

  • Stream mode - Designed to send multiple events per HTTP request.

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

Element

Description

<endpoint>

  • US: https://http-us.devo.io

  • US3: https://http-us3.devo.io

  • Europe: https://http-eu.devo.io

  • Canada: https://http-ca.devo.io

  • Asia-Pacific (APAC):

    • https://collector-ap.devo.io:8443 to ingest in Singapore datanodes

    • https://collector-ap2.devo.io:8443 to ingest in Sydney datanodes

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. See some examples in the section below.

  • 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 some examples 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. 

Sending a single event

Sending multiple events

The stream mode sends multiple events in a single HTTP request. The events must be encoded in the body of the HTTP request using \n as a separator between event messages.

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.

 

Related articles