What is Igloo?

Igloo is a platform that handles the collection of data from IoT devices and allows users to control them remotely.

We have a public API (v1.igloo.ooo) that your devices can interact with to read or write data and apps to visualize it and allow users to interact with the devices.

How does Igloo work?

When building an IoT device with Igloo there are a couple of important pieces:

  • Your device: you will have to build the hardware and write the software to read the data, then send the read data to our servers either by using a library (for example igloo-python ) or by making an HTTP request to our API
  • Igloo’s servers: our servers will receive your data and store it safely so that you can access it from anywhere in the world
  • Igloo Portal: Portal is our app for developers, it allows you to easily control your devices remotely
  • Igloo Remote: if you sell your devices to others, they can use the Remote app or website to access their devices; we offer plans that allow you to customize Remote with your brand
How do I use Igloo?

The first step is creating an account, you can do that through Igloo Portal.

To interact programmatically with Igloo you need a token, this will replace your password for authentication. You can create a token going in the “Account” tab in the settings and then clicking “Manage tokens”, once you created a token you can copy it by clicking on the 3 vertical dots menu. It should look something like this:

eyJ0eXAiOiJKV1QiLCJwdcciOiJIUzUxMiJ9.eyJ1c2VySWQiOiJiMmM5OGI1NS1jMTBhLTRmMzUtYjFlZS1hMmRhYWZmN2QzYT32nCJ0b2tlbklkIjoiZTdiMmMxZjUtOTgxOS00NTYzLThjZjEtOTg0ZjNlNzQ4NTZhIiwiYWNjZXNzTGV2ZWwiOiJUSElORyIuennRva2VuVHlwZSI6IlBST0dSQU1NQVRJQ19BQ0NFU1MifQ.tQTNRTufukb72AHhvPVjA2SC_LhER-WqUc0rvFVnwaai_j0lrBvMXkP3MjYGNatl7O1gWSRkijz5g4i0eH_9fw

Now that you have a token you can experiment with our API, the best way to do that is using our playground. On the bottom you will find an “HTTP Headers” tab, click on it and you will be able to add the token you just created so that the API can authenticate you. To pass your token add a JSON like this one:

{
  "Authorization":"Bearer your-token"
}

You are all set to send requests to the Igloo server, on the left you can write the request and you can send it by clicking the play button in the center, on the right side you will see the response from the server. To check that everything is working try sending this request:

query {
  user {
    email
  }
}

It should return a JSON with the email you signed up with, for example:

{
  "data": {
    "user": {
      "email": "john@igloo.ooo"
    }
  }
}
What requests can I make?

You now know how to send requests to Igloo, so what requests can you make? Our API uses the GraphQL language for the requests, if you really don’t want to, you don’t need to learn it: you can just use the libraries we wrote for you, but it is easy to learn and a great way to experiment with Igloo before writing the code for your device.

A short GraphQL introduction

GraphQL has 2 types of requests:

  • query is used to read data from Igloo, for example getting the list of all your devices
  • mutation is used to add, update or remove data from igloo, for example creating a new device

And one special request type: subscription , which is used to get live updates when an event is triggered, but we will get to it later.

Queries

GraphQL allows you to specify exactly what data you want to read. For example, if you want to get data about the user you don’t have to read all the fields that it contains: you could read only the name:

query {
  user {
    name
  }
}

Or the some settings:

query {
  user {
    lengthAndMass
    temperature
    timeFormat
    dateFormat
  }
}

Or a lot of other fields, we will go over them little by little in these guides, but you can also find all the information in the docs available both from the playground and on this site.
You can also do more complex queries, for example a field on user could have subfields:

query {
  user {
    accessTokens(limit: 1) {
      name
    }
  }
}

As you can see accessTokens requires a parameter limit that specifies how many tokens to read at most, the result of the query will contain an array with at most limit access tokens.

Mutations

Mutations are very similar to queries, but you need to write mutation at the beginning:

mutation {
  createThing(type: "Thermometer") {
    id
  }
}

The only reason they are kept separate is that queries only read data (if you have experience with HTTP requests, they work like a GET request), whereas mutations change the data stored (they work like a POST, PUT or a DELETE request).