Overview

HTTP is the main internet protocol for information exchange on the Internet. It also supports data encryption, which is usually called secure HTTP or HTTPS. When you use a web browser (Firefox, Chrome, Edge, etc.), you send and receive packets using HTTP or HTTPS. Because of this, it is not surprising that HTTPS has become a popular option for IoT data exchange.

When developers implement HTTPS communication, they should look for a RESTful Application Programming Interface, or REST API, which exposes all the endpoints required to interact with a third-party application (like Ubidots). In this section, you can find a reference for our REST API v1.6 that explains how to send data to and retrieve data from our servers.

Note: Our goal with this section is to help you understand what’s happening behind the scenes when communicating with Ubidots, enabling you to replicate it within your own firmware. That's why we avoid using our custom libraries in all the examples.

📘

New HTTPS API v2.0

Please note that our newest API version (v2.0) is documented here.

HTTP requests

The following methods are specified within the HTTP standard:

HTTP is a request/response protocol, which means that every request you make is answered by the server. This response includes a response code and a body. For example, when you make a request to retrieve a file from a website (e.g., "Get me the file 'website.html'"), you are effectively sending a GET request. If the request is correct, the server will typically return a 200 response code, along with the requested body; in this case, the file.

Following the same logic, when a device sends a GET request to the Ubidots server (i.e., requesting the last value of a variable), the server sends back a response with the status of the request (response code) and a body, which contains the value, its context, and its timestamp.

An HTTP request also needs the following parameters:

• Host: Specifies the server you will make HTTP requests to, e.g., industrial.api.ubidots.com

• Path: This is typically the remaining portion of the URL that specifies the resource you want to consume. For example, if an API endpoint is industrial.api.ubidots.com/api/v1.6/devices/my-device, the path is /api/v1.6/devices/my-device.

• Headers: Define the operating parameters of the HTTP request, such as X-Auth-Token, Content-Type, Content-Length, etc.

• Body/payload: In POST and PATCH requests, the body is the data sent to the server, usually as stringified JSON. By convention, GET requests should not have a body because they are meant to request data, not send it.

Ubidots accepts data as JavaScript Object Notation, or JSON. JSON is a common HTTP data type and a collection of name/value pairs. In various programming languages, this is treated as an object, record, struct, dictionary, hash table, keyed list, or associative array. It is also human-readable and language-independent. An example of JSON that Ubidots accepts can be seen below:

{"temperature": {"value":10, "timestamp": 1534881387000, "context": {"machine": "1st floor"}}}

A typical HTTP request to Ubidots should be set up as shown below:

POST {PATH} HTTP/1.1<CR><LN>
Host: {HOST}<CR><LN>
User-Agent: USER_AGENT<CR><LN>
X-Auth-Token: {TOKEN}<CR><LN>
Content-Type: application/json<CR><LN>
Content-Length: {PAYLOAD_LENGTH}<CR><LN><CR><LN>
{PAYLOAD}
<CR><LN>

Where:

• {PATH}: Path to the resource to consume
  Example: /api/v1.6/variables/ to get the user's variable information.

• {HOST}: Host URL.
  Example: industrial.api.ubidots.com

• {USER_AGENT}: An optional string used to identify the type of client, whether by application type, operating system, software vendor, or software version of the requesting user agent.
  Examples: ESP8266/1.0, Particle/1.2

• {TOKEN}: Unique key that authorizes your device to ingest data inside your Ubidots account.

• {PAYLOAD_LENGTH}: The number of characters of your payload.
  Example: The payload {"temperature": 20} will have a content-length of 19.

• {PAYLOAD}: Data to send.
  Example: {"temperature": 20}

📘

Pro Tip

An easy way to handle HTTP and HTTPS requests is to use cURL, a command line tool. To learn how to install cURL on Windows, MacOSX, or Linux, please refer to this guide.