Introduction

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/graphql) 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 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, so you’ll need to know the basics of GraphQL to interact with Igloo.

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 from the playground.
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 REST, they work like a GET request), whereas mutations change the data stored (they work like a POST, PUT or a DELETE request).

Making requests outside of the playground

The playground is a great way to play around with Igloo, but when you are ready to write some code you can interact with Igloo via HTTP requests. We have a C++ guide and a Python guide on how to do this step by step.

If you using another language, then to run a query or a mutation you just need to send an HTTP request to v1.igloo.ooo/graphql formatted as follows:

• the request should be a POST request (both for queries and mutations)
• in the header Authorization you should pass the authorization token as follows: Bearer your_token, where your_token is the token you generated before
• the body of the request should be a JSON with a field “query” that contains your query or mutation (the field is always named query, even if you are sending a mutation).
  E.g. To send a query fetching your user’s email the body should be {"query":"{user{email}}"}
• the header Content-Type should be set to application/json

If you are writing the HTTP requests by hand be sure to escape the JSON correctly.