Skip to content

API Docs

Welcomet to the Hrbr API. Today we only expose a couple of elements of our API during the alpha. Everything in the system is accessible via the API (such as adding users, beacons, foghorns, etc.), but we won't be exposing those endpoints until the beta release. But for now you can do the two most important things on the system.

  1. Send beacon messages to get data into HarborIconWhite
  2. Connect to a wss stream to view and manipulate those messages in your environments and code.

Info

If you want to quickly brush up on our terminology, feel free to take a quick refresher at the Basic Terminology.

Before you start using the API you will also need to set up your app in the Hrbr UI. Click here for a Quick Start Guide for complete instructions on how to do that.


Short Cuts

For those who don't like reading docs here is a quick Curl Example and a super easy Postman link to dive right in.

Curl

curl -i -X POST \
  https://harbor-stream.hrbr.io/beacon \
  -H 'Content-Type: application/json' \
  -H 'apiKey: YOUR_API_KEY' \
  -H 'appVersionId: APP_VERSION_ID' \
  -H 'beaconInstanceID: UNIQUE_SYSTEM_IDENTIFIER' \
  -H 'beaconMessageType: TYPE_OF_MESSAGE' \
  -H 'beaconVersionID: BEACON_VERSION_ID' \
  -H 'cache-control: no-cache' \
  -d '{
    "YOUR":"VALID_JSON"
}'

Postman

Run in Postman


What you need from cloud.hrbr.io

Get your apiKey

Currently Hrbr uses your apiKey to authenticate all requests. You can find your apiKey under your avatar at Hrbr Cloud by clicking your avatar in the upper right hand corner. apiKey

Get your appVersionId and App Hrbr UUID

You will have to have an app registered in the Hrbr UI. You can find the AppVersionId and App Hrbr UUID on the applications page.

Warning

You want to use the AppVersionId not the App Hrbr UUID for your posts.

appVersionID

Get your beaconVersionId

The beaconVersionId will also need to be registered for the related appVersionId. You can find it by hitting the pencil icon on the app page.

beaconVersionId


Send Beacon messages

The basis of all that is Hrbr. Send a boat load of messages. Why not? The first 5 million every month are free. So let's start sending.

Beacon Message Parameters

The basic format of a Beacon message is an HTTPs post with 7 header fields.

Info

The url for sending a beacon is https://harbor-stream.hrbr.io/beacon

Paramater Value Paramater
Type
Data
Type
Req? Description
Content-Type application/json header string YES Lets us know we are getting JSON
apiKey YOUR_API_KEY header string YES Your API Key
beaconVersionId BEACON_VERSION_ID heder string YES The name of the beacon you are sending
appVersionId APP_VERSION_ID header string YES The ID of the app in Hrbr you want this beacon to identify with
beaconInstanceId UNIQUE_SYSTEM_ID header string NO Takes an identifier suce as a HOSTNAME or MAC address so you can tell what system sent the beaon
beaconMessageType TYPE_OF_MESSAGE header string KIND_OF This is a meta field that allows you to look at similar beacons from multiple beaconVersionId's. While this field is not mandatory, most of the UI features in cloud.hrbr.io require a beaconMessageType.
dataTimestamp TIME_STAMP_FROM_BEACON header integer NO Hrbr will put a timestamp on every message received at the time it is received. If you are sending delayed messages or want the exact time something occured on your system you can add your own timestamp.

Samples

Remember you can check here for a curl example or here for a Postman example.


Connect to outbound Beacon streams

Connecting to a beacon stream is a little different than a standard https post or get as we send the streams down a web-socket.

Connecting to an outbound stream: The format of the URL is as follows:

wss://harbor-stream.hrbr.io/stream/YOUR_API_KEY
wss://harbor-stream.hrbr.io/stream/YOUR_API_KEY/beacon/BEACON_UUID
wss://harbor-stream.hrbr.io/stream/YOUR_API_KEY/beacon/BEACON_UUID/type/BEACON_MESSAGE_TYPE
wss://harbor-stream-hrbr.io/stream/YOUR_API_KEY/application/APP_UUID
wss://harbor-stream.hrbr.io/stream/YOUR_API_KEY/application/APP_UUID/type/BEACON_MESSAGE_TYPE

You can receive a stream in three ways.

All Message Stream

Parameter Required Description
YOUR_API_KEY YES Your API Key

This will send out every message on your API key which for now means every message coming into your organization. See here to find out how to get your apiKey.

Sample url:

wss://harbor-stream.hrbr.io/stream/e973ca712cbf357ca071ab85a582b4c7

Message by Beacon

Parameter Required Description
YOUR_API_KEY YES Your API Key
BEACON_UUID YES
BEACON_MESSAGE_TYPE NO You can assign a beacon message type as an additional filter

Warning

Since streams require params in the URL we use the Beacon UUID here not the beaconVersionId.

Sample url:

wss://harbor-stream.hrbr.io/stream/e973ca712cbf357ca071ab85a582b4c7/beacon/953d849c-e365-1004-8599-42b1febe886f/type/MONGOINFO

Message Stream by App

Parameter Required Description
YOUR_API_KEY YES Your API Key
BEACON_UUID YES
BEACON_MESSAGE_TYPE NO You can assign a beacon message type as an additional filter

Warning

Since streams require params in the URL we use the App Hrbr UUID here not the appVersionId.

Sample url:

wss://harbor-stream.hrbr.io/stream/e973ca712cbf357ca071ab85a582b4c7/application/4539a508-e3aa-1004-8710-6bb8457af470/type/MONGOINFO

Test your streams

The simplest way to see your Web Socket streams is directly at Hrbr Cloud. There you can go to developer console and choose raw console to see your Web Socket stream and the actuall url.

Raw Console

To check other streams here are two of many ways to check yours.

  1. Check it out in browser at websocket.org.
  2. Install a Chrome extension such as Simple Web Socket.

There you have it. Stay tuned for even more examples and calls in the future.