HTTP

HTTP connection

This connector allows data to be transferred from/to the Everynet Network Server to a specific HTTP server hosted by the user.

In order to enable the HTTP adapter, you should create a new Connection at the Everynet Management API or Network Server Interface, select 'HTTP / HTTP Adapter' and use the following arguments:

Argument Required Description
description no Description of connection
filter yes Network Server Filter ID
url yes URL of your server, more description below
authorization no Authorization header value, more description below

URL

Example:

https://login:password@example.com:1234/messages/{type}/{device}

Field substitution is only applied for parts after the port field (path, params, query, hash)

If the field is not present, it will be left as is, eg /messages/{type}/{device}

List of fields that could be substituted:
device The device EUI (dev_eui by LoraWAN specification)
device_addr The device address (dev_addr by LoraWAN specification)
application The application EUI (app_eui by LoraWAN specification)
gateway The gateway mac address
network The network of gateways identifier
type The type of message (uplink / join / error / e.t.c.)

Authorization

You can specify an Authorization header value.

This field is mandatory if you are going to send requests TO the Network Server.

This value is used for both sides of the request.

  • The connector will send requests to your application with that header.
  • The connector expects this header to be of the same value, if you send a request.

Example:

If you specify the field like

"authorization": "Token 123"

The requests will contain the header, and expect the same from your application, if it makes requests

Headers:
...
Authorization: Token 123
...

Receiving messages from the Network Server

The connector performs two types of HTTP requests to your application: POST and OPTIONS

Messages from the NS come as POST requests (the example is provided below)

A request is considered successful by the connector if the response is HTTP 2xx or HTTP 4xx.

The connector has 4 seconds to perform the connection to your application (including SSL handshake), and then 1 second to receive a response. The request should be received within these timeouts to be considered successful.

Respond as soon as you can. Avoid actually processing and reacting to events within the same process. Implement a queue to handle inbound events after they are received.

The connector supports keep-alive connections and maintain up to 10 parallel connections.

Send messages to the Network Server

If your response is HTTP 2xx response mime type is application/json and contains valid JSON, then the payload will be forwarded to the NS.

If your response is HTTP 4xx, then the response body is ignored.

If your response is HTTP 5xx then the request is treated as failed.

Request error handling and retries

Your application may respond with a HTTP 3xx and we will follow up with two redirects, until you provide a HTTP 2xx or HTTP 4xx success code.

If your request is failed, we will retry it 2 times , increasing the interval between them.

Each request comes with custom headers set to support retries logic

  • Request-Id : unique ID of the request. It is the same for all retries.

  • Retry-Number : present if the request is a retry and contains the retry sequence number. 

    Request-Id: 93c437e8-6e88-11ea-87f8-9da0f1c114a3
Retry-Number: 2

A request is treated as failed if it fails all retries. In this case, the last error will be stored to the connection logs.

There is an error rate counter inside, monitoring the last 600 seconds or 10000 requests. That counter includes both POST and OPTIONS.

If you have 5% or more failed requests to you application, then your connection will be temporarily disabled for 60 seconds.

The connections that have a rate of less than 100 requests per 600 seconds will not be disabled.

Working cycle

After connection is initialized or being disabled, the connector tries to make a health check of your application using an OPTIONS request.

If the first request is a success, the connection is treated as open and the traffic starts to flow.

If you have no requests from the NS for 10 seconds, the OPTIONS check request will be sent.

If your error rate is high enough to fail, the connection will be temporary disabled, and all tcp sockets to your application will be closed.

The connection working cycle starts from the beginning once the disabling timeout expired.

Requests from the application

The URL for the requests

https://adapters.ns.< your_region >.everynet.io/http2/cb/< your_connection_id >

You can send the requests to the Network Server with HTTP requests to that URL.

All rules applied to this request are similar to the response of your application, but you MUST specify the Authorization header (please refer to it's section).

You can specify an Authorization header value.

Examples of usage

Connection check

In order to check if your server is available or not, the connector will make a check.

Periodically, it will send the OPTIONS request to your application, which you must reply with some proper HTTP response.

Example:

OPTIONS /lora/%7Bdevice%7D/%7Btype%7D HTTP/1.1
Connection: keep-alive
Accept-Encoding: gzip, deflate
Accept: */*
Host: example.com
Content-Length: 0
Request-Id: 93c437e8-6e88-11ea-87f8-9da0f1c114a3



HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Allow: POST, OPTIONS
Content-Length: 0
Date: Mon, 16 Jul 2018 10:38:10 GMT

What this example is about:

  • You have an HTTP server with the following URL: http://example.com
  • You will receive uplink messages to the server endpoint http://example.com/uplink and downlink_request messages to http://yourserver.com/downlink_request.

What you should do:

  1. Create a filter in the NS for the data you want to receive. Select uplink and downlink_response types.
  2. Create an HTTP connection with the following URL: http://example.com/{type} and Filter ID of the filter you have just created.
  3. After that, the server will send you a connection-check request to your application
OPTIONS /example HTTP/1.1
Connection: keep-alive
Accept-Encoding: gzip, deflate
Accept: */*
User-Agent: everynet-http
Host: example.com
Authorization: b24023b99492fc94
Content-Length: 0
Request-Id: 93c437e8-6e88-11ea-87f8-9da0f1c114a3



HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Allow: POST, OPTIONS
Content-Length: 0
Date: Fri, 20 Jul 2018 06:53:53 GMT

If your application responded to that, the connector starts to send messages to your application.

Example of an uplink message:

POST /uplink HTTP/1.1
Connection: keep-alive
Accept-Encoding: gzip, deflate
Accept: */*
User-Agent: everynet-http
Host: example.com 
Content-Length: 543
Content-Type: application/json
Request-Id: 93c437e8-6e88-11ea-87f8-9da0f1c114a3

{"params": {"payload": "MzQ3NjcwNjFiNDc3NGU2ZmFiZjBhNmY4YTJjYmI0Y2M=", "port": 7, "duplicate": false, "counter_up": 3, "rx_time": 1532073817.157281, "encrypted_payload": "pLgR8Tzh3JptkhtozJ5OlFuS3zQCygWD5hmx9zMjLnU="}, "meta": {"network": "e23d2f31af81b25ef50375b5b7810c52", "packet_hash": "73465c1ed0cae413816d0f78baf3dcc2", "application": "1293e9e373666fd5", "device_addr": "d242b7a6", "time": 1532073817.175208, "device": "b2b48f713c2f973d", "packet_id": "f577207419bb4701ff9f7874c2e2808e", "gateway": "92a199d4e41ab64b"}, "type": "uplink"}

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 0
Date: Fri, 20 Jul 2018 08:03:37 GMT

Example of a downlink_request message and a downlink_response reply

POST /downlink_request HTTP/1.1
Connection: keep-alive
Accept-Encoding: gzip, deflate
Accept: */*
User-Agent: everynet-http
Host: example.com
Content-Length: 412
Content-Type: application/json

{"params": {"counter_down": 3, "max_size": 51, "tx_time": 1532075747.295559}, "meta": {"network": "12b5d8a8df8d9255c65d6d565d836a9d", "packet_hash": "cf59f7bf410a9eb23383f41342c3c7fe", "application": "6264dd6a1b4e9ca1", "device_addr": "f22eef89", "time": 1532075746.335046, "device": "c20ba71a9affafc6", "packet_id": "a8b464039cca609bed00f8ec58f494fe", "gateway": "524d07d7ef40dea3"}, "type": "downlink_request"}


HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 476
Date: Fri, 20 Jul 2018 08:35:46 GMT

{
  "meta": {
    "application": "6264dd6a1b4e9ca1", 
    "device": "c20ba71a9affafc6", 
    "device_addr": "f22eef89", 
    "gateway": "524d07d7ef40dea3", 
    "network": "12b5d8a8df8d9255c65d6d565d836a9d", 
    "packet_hash": "cf59f7bf410a9eb23383f41342c3c7fe", 
    "packet_id": "a8b464039cca609bed00f8ec58f494fe", 
    "time": 1532075746.335046
  }, 
  "params": {
    "counter_down": 3, 
    "payload": "220de733f4", 
    "port": 50
  }, 
  "type": "downlink_response"
}

Class C downlink_claim

You can also send this type of message as a response to your application.

1-3. Repeat the same steps for Simple flow example 4. If you want to send a downlink_claim message, you have to set the authorization parameter in the connection. It will be used to check requests from your application to the connector for security verification.

For example

  • Authorization = Token 1234567890 (The same as an authorization field in the connection you have set)
  • Connection ID = 5b51a9a8e15b770005c928c9
POST /http2/cb/5b51a9a8e15b770005c928c9 HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Authorization: Token 1234567890
Connection: keep-alive
Content-Length: 142
Content-Type: application/json
Host: adapters.ns.eu.everynet.io
User-Agent: HTTPie/1.0.0-dev

{
    "meta": {
        "device": "d2953b67bca671a6", 
        "network": "12024f9efc46a98120a6fac272a9c3a4"
    }, 
    "type": "downlink_claim"
}

HTTP/1.1 202 Accepted
Connection: keep-alive
Content-Length: 0
Content-Type: text/html; charset=utf-8
Date: Fri, 20 Jul 2018 09:47:30 GMT

results matching ""

    No results matching ""