HTTP API

Introduction

The HTTP API is the most suitable method for sending data to a W3bstream project when the data publisher is a server, mobile client, or smart device as these are typically always connected and not constrained in terms of data volume or bandwidth.

Authentication

Please refer to the Client Authentication Patterns section.

Finding your Project's HTTP route

Before sending data to a specific project in W3bstream using the HTTP API, you will need to obtain the HTTP route of the project. You can find this information in W3bstream Studio on the Project's 'Events' page.

Data API

Sending from an individual publisher

Send Data to a W3bstream Project

POST https://devnet-prod-api.w3bstream.com/event/<PROJECT_NAME>

Sends a data payload to a specific W3bstream project for processing

Path Parameters

Name	Type	Description
eventType	String	The Project-defined event to be raised
timestamp	String	The timestamp when the message was sent by the client

Headers

Name	Type	Description
Authorization*	String	The publisher authentication token (Bearer)

200: OK

Example Request

URL

https://devnet-prod-api.w3bstream.com/event/eth_0x2c37a2cbcfaccdd0625b4e3151d6260149ee866b_energy_sharing

Header

{ Authorization: Bearer w3b_MV8 ... I8Jg}

Body

{ 
    Temperature: 24.3,
    Latitude: 118.65789
    Longitude: 94.223321
}

Response

{
  "channel": "eth_0x2c37a2cbcfaccdd0625b4e3151d6260149ee866b_energy_sharing",
  "publisherID": "1038110072263586821",
  "publisherKey": "001",
  "eventID": "31fed038-8f10-48d5-958e-f9131754c85b_w3b",
  "timestamp": 1695401468899,
  "results": [
    {
      "appletName": "299519632338498561",
      "instanceID": "299519632338509832",
      "handler": "start",
      "returnValue": null,
      "code": 0
    }
  ]
}

Sending on behalf of publishers

This API facilitates the transmission of data from a single source (usually a cloud service receiving data from the actual devices/publishers) on behalf of individual publishers. In this scenario, the body of the HTTP request should be an array of JSON objects, where each object represents a data message associated with a specific device ID. These data messages must include the respective device ID and the event type that is intended to be triggered in W3bstream. The API URL will incorporate a unique eventType, designated as 'DA-TA_PU-SH', to differentiate this request from those involving a single publisher sending a data message.

It's important to note that the body should be in an array format, even when sending just a single data message.

Send Data to a W3bstream Project

POST https://devnet-prod-api.w3bstream.com/event/<PROJECT_NAME>

Sends a data payload on behalf of publishers to a specific W3bstream project for processing

Path Parameters

Name	Type	Description
eventType	String	In this scenario the eventType in the URL must be equal to "DA-TA_PU-SH"
timestamp	String	The timestamp when the message was sent by the client

Headers

Name	Type	Description
Authorization*	String	The API Key (Bearer) with read/write access permissions to publishers

Request Body

Name	Type	Description
device_id*	String	The unique id of the device you are sending data on behalf of. New devices will automatically be added to the target project.
eventType	String	The Project-defined event to be raised
timestamp	String	The timestamp when the message was sent by the client
payload*	String	A string field including the actual data to be sent to the target W3bstream project

200: OK

Example Request

URL

https://devnet-prod-api.w3bstream.com/event/eth_0x2c37a2cbcfaccdd0625b4e3151d6260149ee866b_energy_sharing?eventType=DA-TA_PU-SH

Header

{ Authorization: Bearer w3b_MV8 ... I8Jg}

Body

[
    { 
        device_id: "UNIQUE_DEVICE_ID_1",
        Temperature: 24.3,
        Latitude: 118.65789
        Longitude: 94.223321
    },
   { 
        device_id: "UNIQUE_DEVICE_ID_2",
        Temperature: 21.3,
        Latitude: 102.12345
        Longitude: 94.223321
    },
]

Response

{
  "channel": "eth_0x2c37a2cbcfaccdd0625b4e3151d6260149ee866b_energy_sharing",
  "publisherID": "1038110072263586821",
  "publisherKey": "001",
  "eventID": "31fed038-8f10-48d5-958e-f9131754c85b_w3b",
  "timestamp": 1695401468899,
  "results": [
    {
      "appletName": "299519632338498561",
      "instanceID": "299519632338509832",
      "handler": "start",
      "returnValue": null,
      "code": 0
    }
  ]
}