Application Broker API API Reference

The Application Broker API is used for connecting applications to the Geeny platform and accessing data from connected data sources via message streams.

In order to use this endpoint, you must first authorize your application to access the data stream from the desired Thing along specific Message Types (i.e., types of data sent by a Thing). You must supply your application's ID (which you can find on its details page) with requests to the Application Broker to query this data.

Data from the message streams is partitioned into shards. You can access this data by iterating over these shards using the API. First, you must describe the Message Type that you would like to retrieve data from, and then you must create iterators for accessing the data from each shard.

The Application Broker API is secured by the Application Access Key. You must supply this token with each request as an Authorization header in the form of: "Authorization: Bearer <token>". You can find this token on your application's details page.

API Endpoint
https://developers.geeny.io/ab
Schemes: https
Version: 2.0.0

Authentication

APIKey

description

Your application access key, which Geeny will provide to the application upon deployment via environment variable. This value should consist of "Bearer <key>". "<key>" is the access key value which you can acquire on the application's detail page.

name
Authorization
in
header

Subscribe

Operations for receiving data from data sources and iterating over it.

Get list of shards

GET /subscribe/{applicationId}/messageType/{messageType}

Returns an array of shards of the given message type. To iterate over a shard and access its data, you must supply the returned shardId to the "Create Shard Iterator" request.

applicationId

ID of the application requesting access to the message stream.

type
string
in
path
messageType

The message type to be described.

type
string
in
path

Request successful - shard IDs returned.

400 Bad Request

Invalid message type or app ID or something went wrong with your request.

401 Unauthorized

Invalid Authorization token.

Response Content-Types: application/json
Response Example (200 OK)
{
  "shards": [
    {
      "shardId": "a81a8d9c-5ea4-45e7-ae63-6e9e5610b112"
    }
  ]
}

Create shard iterator

POST /subscribe/{applicationId}/messageType/{messageType}/iterator

Creates an iterator for querying data in a shard. The "type" property supplied with the request defines the position from which to start querying data within the shard that is being iterated over. Iterators expire in 30 seconds, after which you must create a new iterator in order to request more messages.

You must make the "Get list of shards" request before you can use this method.

Request body for creating an iterator. See the schema description for more information about its properties.

applicationId

ID of the app requesting access to the message stream.

type
string
in
path
messageType

Message type of the stream to be accessed.

type
string
in
path
Request Content-Types: application/json
Request Example
{
  "shardId": "a81a8d9c-5ea4-45e7-ae63-6e9e5610b112",
  "iteratorType": "string",
  "startingSequenceNumber": "8f782a18-f19d-4eae-9dc2-db369116c339",
  "maxBatchSize": "integer"
}

Iterator created.

400 Bad Request

Invalid request.

401 Unauthorized

Invalid Authorization token.

Response Content-Types: application/json
Response Example (200 OK)
{
  "shardIterator": "1ad07c6d-b881-4586-b7f8-1545a6a8e647"
}

Get message data

GET /subscribe/{applicationId}/messageType/{messageType}/iterator/{iteratorId}

Returns an array of messages sent by Things to the Geeny platform using the specified iterator. You must make the "Create shard iterator" request before you can use this method.

applicationId

ID of the app requesting access to the message stream.

type
string
in
path
messageType

Message type of the stream to be accessed.

type
string
in
path
iteratorId

ID of the iterator used to query the messages.

type
string
in
path

Messages returned.

401 Unauthorized

Invalid Authorization token.

404 Not Found

The iterator expired. Create a new iterator (POST /{applicationId}/messageType/{messageType}/iterator) and try the request again.

Response Content-Types: application/json
Response Example (200 OK)
{
  "messages": [
    {
      "shardId": "a81a8d9c-5ea4-45e7-ae63-6e9e5610b112",
      "sequenceNumber": "8f782a18-f19d-4eae-9dc2-db369116c339",
      "payload": "ewogICJhY3RpdmVLaWxvY2Fsb3JpZXMiOiAwLAogICJhY3RpdmVUaW1lSW5TZWNvbmRzIjogMAp9",
      "userId": "0f1b1500-1f70-4136-a00a-9d1d0c8e744f",
      "thingId": "bdba438a-ec18-4ef0-853a-d8ca1f542d10",
      "messageId": "15e1b268-1d5c-4844-97e9-eb2c7f89664c"
    }
  ],
  "nextIterator": "1ad07c6d-b881-4586-b7f8-1545a6a8e647"
}

Create Checkpoint

POST /subscribe/{applicationId}/messageType/{messageType}/checkpoint

Creates a checkpoint in a shard at the specified sequencing position. This method is useful for saving a position from which you can query data regardless of how much comes in through the stream later on. Multiple shards can be checkpointed with this method if you provide an array of checkpoint request bodies.

Request body for creating a checkpoint. Must include the ID of the shard and the sequencing position at which the checkpoint will be created.

applicationId

ID of the app requesting access to the stream.

type
string
in
path
messageType

Message type of the shard where the checkpoint is being created.

type
string
in
path
Request Content-Types: application/json
Request Example
{
  "checkpoints": [
    {
      "shardId": "a81a8d9c-5ea4-45e7-ae63-6e9e5610b112",
      "sequenceNumber": "8f782a18-f19d-4eae-9dc2-db369116c339"
    }
  ]
}
200 OK

Checkpoint created.

400 Bad Request

Invalid data supplied with the request.

401 Unauthorized

Invalid Authorization token.

Response Content-Types: application/json

Subscribe using WebSocket to get message data

GET /subscribe/{applicationId}/messageType/{messageType}/ws

Pushes messages sent by Things to the Geeny platform using the specified iterator type.

applicationId

ID of the application requesting access to the stream.

type
string
in
path
messageType

Message Type of the shard where the checkpoint is being created.

type
string
in
path
iteratorType

Specifies the position from which messages will be read from stream. Currently only EARLIEST and LATEST types are supported. See the schema description for more information about its properties.

type
string
in
query
101 Switching Protocols

Websocket connection established.

400 Bad Request

Invalid data supplied with the request.

401 Unauthorized

Invalid authorization token.

Response Content-Types: application/json
Response Example (101 Switching Protocols)
{
  "shardId": "a81a8d9c-5ea4-45e7-ae63-6e9e5610b112",
  "sequenceNumber": "8f782a18-f19d-4eae-9dc2-db369116c339",
  "payload": "ewogICJhY3RpdmVLaWxvY2Fsb3JpZXMiOiAwLAogICJhY3RpdmVUaW1lSW5TZWNvbmRzIjogMAp9",
  "userId": "0f1b1500-1f70-4136-a00a-9d1d0c8e744f",
  "thingId": "bdba438a-ec18-4ef0-853a-d8ca1f542d10",
  "messageId": "15e1b268-1d5c-4844-97e9-eb2c7f89664c"
}

Publish

Operations for sending commands to data sources.

Send command

POST /publish/{applicationId}/messageType/{messageTypeId}/messages

Sends an array of commands to one or more Things of a specific Thing Type along a specific Message Type.

Array of commands to be delivered to Things.

applicationId

ID of the application sending the command.

type
string
in
path
messageTypeId

ID of the Message Type used for sending the command.

type
string
in
path
messageId

Optional UUID to assign to this message.

type
string
in
path
Request Example
{
  "messages": [
    {
      "payload": "ewogICJsaWdodE9uIjogInRydWUiCn0=",
      "userId": "7cb6c116-32d5-45c3-908f-6e7eb3660900",
      "thingId": "25f72b0f-10d0-4acd-848c-20bf0daa5f11"
    }
  ]
}
200 OK

Command sent.

400 Bad Request

Invalid data supplied with the request.

401 Unauthorized

Invalid Authorization token.

Schema Definitions

ShardsResponse: object

Response body of the Describe Message Type operation. Consists of an array of shards.

shards: object[]
Example
{
  "shards": [
    {
      "shardId": "a81a8d9c-5ea4-45e7-ae63-6e9e5610b112"
    }
  ]
}

Shard: object

Shard object returned by Describe Message Type operation. Consists merely of the shard ID.

shardId: shardId
Example
{
  "shardId": "a81a8d9c-5ea4-45e7-ae63-6e9e5610b112"
}

IteratorRequest: object

Request body for creating an iterator. Must include the ID of the shard to be iterated over, the iterator type (defines where to start iterating), the starting sequence number (depending on the iterator type), and the maximum size of the batch to be iterated over.

shardId: shardId
iteratorType: iteratorType
startingSequenceNumber: sequenceNumber
maxBatchSize: integer x ≤ 1 | x ≤ 500
Example
{
  "shardId": "a81a8d9c-5ea4-45e7-ae63-6e9e5610b112",
  "iteratorType": "string",
  "startingSequenceNumber": "8f782a18-f19d-4eae-9dc2-db369116c339",
  "maxBatchSize": "integer"
}

IteratorResponse: object

A UUID representing a shard iterator that can be used for querying data.

shardIterator: iteratorId
Example
{
  "shardIterator": "1ad07c6d-b881-4586-b7f8-1545a6a8e647"
}

MessagesResponse: object

Response body from the Request Message Data operation. Consists of an array of messages of a specific type. Each message includes identifying information about itself and its origin (user and Thing), the message payload, its own sequencing number and the number of the next message in the shard.

messages: object[]

Array of messages

nextIterator: iteratorId
Example
{
  "messages": [
    {
      "shardId": "a81a8d9c-5ea4-45e7-ae63-6e9e5610b112",
      "sequenceNumber": "8f782a18-f19d-4eae-9dc2-db369116c339",
      "payload": "ewogICJhY3RpdmVLaWxvY2Fsb3JpZXMiOiAwLAogICJhY3RpdmVUaW1lSW5TZWNvbmRzIjogMAp9",
      "userId": "0f1b1500-1f70-4136-a00a-9d1d0c8e744f",
      "thingId": "bdba438a-ec18-4ef0-853a-d8ca1f542d10",
      "messageId": "15e1b268-1d5c-4844-97e9-eb2c7f89664c"
    }
  ],
  "nextIterator": "1ad07c6d-b881-4586-b7f8-1545a6a8e647"
}

Message: object

A message sent to the Geeny platform.

shardId: shardId
sequenceNumber: sequenceNumber
payload: string (base64)

Data contents of the message.

userId: string (uuid)

The user whose Thing sent the message.

thingId: string (uuid)

The Thing that sent this message to the platform.

messageId: string

Unique ID of this message local to the Thing and message type. Useful for deduplication.

Example
{
  "shardId": "a81a8d9c-5ea4-45e7-ae63-6e9e5610b112",
  "sequenceNumber": "8f782a18-f19d-4eae-9dc2-db369116c339",
  "payload": "ewogICJhY3RpdmVLaWxvY2Fsb3JpZXMiOiAwLAogICJhY3RpdmVUaW1lSW5TZWNvbmRzIjogMAp9",
  "userId": "0f1b1500-1f70-4136-a00a-9d1d0c8e744f",
  "thingId": "bdba438a-ec18-4ef0-853a-d8ca1f542d10",
  "messageId": "15e1b268-1d5c-4844-97e9-eb2c7f89664c"
}

CheckpointsRequest: object

Request body for creating a checkpoint. Must include the ID of the shard and the sequencing position within the shard at which the checkpoint will be created.

checkpoints: object[]

Checkpoint entity

Example
{
  "checkpoints": [
    {
      "shardId": "a81a8d9c-5ea4-45e7-ae63-6e9e5610b112",
      "sequenceNumber": "8f782a18-f19d-4eae-9dc2-db369116c339"
    }
  ]
}

Checkpoint: object

A saved sequence number (ID of a specific message) within a shard. Useful for creating a point from which you can iterate on a set of data in the future without having to query the entire shard again.

shardId: shardId
sequenceNumber: sequenceNumber
Example
{
  "shardId": "a81a8d9c-5ea4-45e7-ae63-6e9e5610b112",
  "sequenceNumber": "8f782a18-f19d-4eae-9dc2-db369116c339"
}

CommandRequest: object

Request body for sending commands to Things.

messages: object[]

Array of commands to be sent simultaneously.

Example
{
  "messages": [
    {
      "payload": "ewogICJsaWdodE9uIjogInRydWUiCn0=",
      "userId": "7cb6c116-32d5-45c3-908f-6e7eb3660900",
      "thingId": "25f72b0f-10d0-4acd-848c-20bf0daa5f11"
    }
  ]
}

Command: object

A command sent to a Thing.

payload: string (base64)

Base64-encoded payload to be delivered to the Things.

userId: string (uuid)

User ID of the Thing owner.

thingId: string (uuid)

ID of the Thing to receive the command. See the onboarding guide for more information.

Example
{
  "payload": "ewogICJsaWdodE9uIjogInRydWUiCn0=",
  "userId": "7cb6c116-32d5-45c3-908f-6e7eb3660900",
  "thingId": "25f72b0f-10d0-4acd-848c-20bf0daa5f11"
}

shardId: string

ID of the shard.

iteratorId: string

UUID of an iterator used for iterating over a shard to retrieve messages.

sequenceNumber: string

UUID of a message sent by a Thing. Accessed by iterating over a shard of data of the message's type.

iteratorType: string

string LATEST, EARLIEST, AT_SEQUENCE_NUMBER, AFTER_SEQUENCE_NUMBER, LAST_CHECKPOINT