Developer Center



MQTT Overview MQTT - API IDs and UIDs
GS SQL Overview HTTP - API Dates and Times
HTTP Overview HTTP - Advanced API Sandbox

APIs Overview

The MQTT API is the preferred API to use from devices. It is lightweight, low power, low data I/O, scalable, reliable, allows for two-way communication, and is secure.

The HTTP API was the primary API for GroveStreams before MQTT became the standard for IoT systems. Therefore, the GS HTTP API library is far larger than the GS MQTT library. The GS MQTT API library contains an MQTT Publish Topic ({orgUid}/api/http/{apiUrl}) for calling classic GS HTTP APIs. This solution relies on the request-response pattern and is demonstrated in the Raspberry Pi tutorial. The HTTP APIs are still used for almost all of the GroveStreams website design and are recommended for web development.

IDs and UIDs

IDs
Many GroveStreams resources can be identified externally by an ID. IDs are assigned by users, by GroveStreams API calls and are optional. They can be any string with a limit of 512 characters. Examples of resource IDs are a device's serial number, a device's MAC address, or a device data stream's identifier such as "temperature".

UIDs
Each GroveStreams resource is identified internally by a Universally Unique Identifier (UID). UIDs are assigned by GroveStreams and are mandatory. A GroveStreams UID is a version 5 SHA-1 hashed universally unique identifier (UUID).  No two GroveStreams objects have the same uid. Developers should NEVER create their own UIDs for their new GroveStreams entities. Always let GroveStreams create a new entity for you with a unique uid by appending "/new" to your HTTP GET URIs or leave the uid attribute blank during the PUT and GroveStreams will create one for you and return it with the entity that was inserted into the store.

A UID represented as a STRING data type takes 36 characters to represent. Here's an example of a UID: 3F2504E0-4F89-11D3-9A0C-0305E82C3301
A UID represented as a 16-byte (128 bit) number only takes 16 bytes.

The downside of UUIDs is that they are not easy for humans to work with because of the large number of characters and in the STRING format they consume a lot of bytes. So why do we use UUIDs for our internal entity identifiers versus say a unique LONG number?
  • The global uniqueness of a UUID will allow GroveStream entities to be passed around without the worry of "id collisions".
  • UUID generation scales. There is not a single uid generator where a bottleneck can occur and we'll never run out of UUIDs.
  • The SHA-1 hash provides enough randomness to prevent a malicious user from guessing a uid.
  • GroveStreams stores uids as 16 byte representations so they're not consuming much disk space and index look-ups on 16 bytes isn't much slower than say an 8 byte LONG key - at least not enough to outweigh the benefits of UUIDs.
  • In a high performance large distributed store, such as GroveStreams, entities need to be evenly partitioned across hundreds of servers. UUIDs give our entity key indexes the randomness needed for an even distribution across all servers. You don't need to know exactly what this means - just know that it allows you to insert and extract a lot of data very quickly.

Date and Times

We refer to a date and time, with millisecond precision, as datetime throughout our API documentation. The GroveStreams API passes around datetimes as single LONG (8 bytes) data type representing milliseconds since epoch January 1,1970 UTC. This allows for datetimes roughly +- 290 million years to millisecond precision from the epoch. Throughout the API documentation you'll see this format referred to as "epoch millis". Whenever a datetime is discussed in the documentation as a LONG data type it is safe to assume it is in "epoch millis" UTC format.

Handling datetimes as "epoch millis" is common practice in the programming world as it simplifies datetime management and improves performance. Most of the major programming languages have a date or time library that handles the conversion to and from human readable datetimes and "epoch millis". GroveStreams is written in Java 8.0 and 11. It adheres to the JDK standards for managing datetimes.

GroveStreams has support for time zones, leap years and daylight savings time during datetime calculations. GroveStreams does not support leap seconds as most applications don't have a need for this, most computer clocks are not accurate enough to be able to reflect it and supporting it would impact performance.

Sandbox