Overview

Welcome to the GridDuck Developer Guide.

We utilise a standard RESTful HTTP API with OAuth2 authorization to enable third parties to integrate easily and securely with the GridDuck energy management system.

GridDuck also utilises WebSockets to enable you to utilise real-time monitoring of connected assets and sites to the same extent as possible on the dashboard.

Please read our Getting Started Guide to start experimenting with the API and see some basic examples.

Before integrating your systems with GridDuck it is important to choose the appropriate OAuth2 authorization flow. To help you decide please read our Security Guide.

For a full list of HTTP Endpoints check out our HTTP Reference.

Please get in touch at support@gridduck.com if you experience any difficulties.

Getting Started Guide

Introduction

In this tutorial we will show you how to get started with the GridDuck API. We will show you how to generate a personal access token - using the client credentials grant - and show a couple of basic examples of how to use the API to manage assets.

The GridDuck API allows you to manage your assets controlled by the GridDuck cloud in a simple, programmatic way using conventional HTTP requests. The endpoints are RESTful and designed to allow you to easily view data and control your assets. Any action that you can perform through the GridDuck Dashboard - apart from organisation, permission and access token management - can be performed using the API.

Important: The client credentials grant is suitable only for machine-to-machine authentication, i.e. a fully server-side, secure and private application belonging to a single individual or organisation. For details on the other grant types, and which you should use for your specific use case, please refer to the Security Guide.

Generating Client Credentials

The first step to using the API is to create an application, which will yield a Client ID and Client Secret. The Client ID and Secret can then be used to generate an access token from which secure resources in the GridDuck API can be accessed. Applications are created using scopes which dictate what permission level the application has over your resources.

  1. Log in to the GridDuck Dashboard
  2. Click the Account button in the main navigation.
  3. Click the API Integration tab button.
  4. Click the Create New Application button.

Then, on the New Application form:

  1. Enter the application name, for example “My First Application”. This is just for your own reference.
  2. Select the necessary scopes requires for the application to function. For this tutorial select ‘site:view’,’asset:view’ and ‘asset:boost_snooze’.
  3. Select ‘client_credentials’ from the list of permitted grant flow types.
  4. Click the Create Application button

Your application will then be created. Your Client ID is visible next to your application name. To view your Client Secret click the View Client Secret button.

Note: Remember to keep your client secret a secret! They function similarly to passwords. Do not hardcode your client secret into programs where they may accidentally be released. If a client secret becomes compromised reset it by first clicking the View Client Secret button, then clicking the Reset Client Secret button.

Using the API

We will cover some example API requests, using the curl command. This will allow us to demonstrate various endpoints in a simple, textual format. The full API documentation is available here: GridDuck v1 API Reference.

The first step to using the API is to request an access token which is granted in response to the correct Client ID and Client Secret.

Gaining an Access token

To gain your access token send a POST request to https://v1.api.gridduck.com/oauth/token with request data in form data format containing the fields:

grant_type: The grant type, for example “client_credentials” scope: The requested scopes, for example “site:read,asset:view,asset:boost_snooze”

With a Basic Authorization header containing the string ‘clientID:clientSecret’ base64 encoded.

The response contains an access token, the token type (Bearer), and in how much time it expires in seconds.

Example Request:
This example should be run in your terminal.

curl --request POST \ --url 'https://v1.api.gridduck.com/oauth/token' \ --header 'application/x-www-form-urlencoded' \ --header 'Authorization:Basic YzEzYmE1NjctMGMxYy00OGYwLThkZGUtNDZlMTI0YzM4ZjRkOmFiY2RiOWNkLTE5MzctNDljNi1hODliLWFkNTk0ZjQ4MWU5OQ==' \ --data 'grant_type=client_credentials&scope=site%3Aview+asset%3Aview+asset%3Aboost_snooze'

Result

{ "access_token": "7f20856b39db18cde0bd9dd30ca0253d7d037cc8", "token_type": "Bearer", "expires_in": 31535999, "scope": "site:view" }

Secured Requests

Our first example request will be to gather a list of assets associated with your account, using the previously acquired access token. This involves sending a GET request to https://v1.api.gridduck.com/asset/

With the access token sent as a Bearer header in the request.

Example request

curl --request GET \ --url 'https://v1.api.gridduck.com/asset/' \ --header 'application/x-www-form-urlencoded' \ --header 'Authorization:Bearer 655078ba4400494c833212a8b34891f38b380d78'

Result

[ { "code":"0015BC002F003C57", "id":"7ff88487-27b0-4234-b48f-aff17f96770e", "gateway_id":"ba75af52-c3b4-4f76-9a01-7ee864540844", "status":"CONNECTED", "signal_strength":null, "user_state":"ALWAYS_ON", "current_state":"ON", "name":"Alex's Lamp", "site_id":"9050e55a-3067-40f1-a3fd-b6225aac8ad3", "sku":"PLU-UK", "timeswitch_id":"1c90b4f5-96ca-41b6-a540-51d7d6e977ff", "demand":7, "last_contacted_stamp":1520958292, "created_stamp":1519740324, "_permission":"admin", "boost_finish_stamp":0, "snooze_finish_stamp":1519826509 } ]

Next we might want to snooze an asset for 30 minutes, or 1800 seconds. We can send a PUT request to https://v1.api.gridduck.com/asset/{asset_id}/snooze, where {asset_id} is the ID of the asset you wish to snooze, with the body containing JSON of the following object:

{ "duration": 1800 }

Example request

curl --request PUT \ --url 'https://v1.api.gridduck.com/asset/7ff88487-27b0-4234-b48f-aff17f96770e/snooze' \ --header 'Content-Type: application/json' \ --header 'accept: application/json' \ --header 'Authorization:Bearer 655078ba4400494c833212a8b34891f38b380d78' \ --data '{"duration": 60}'

You will receive a HTTP 204 response indicating successful snoozing.

Security Guide

The GridDuck API utilises the OAuth2 Authorization framework.

Authentication for an application which contains the credentials of a specific user/organisation is utilised by using a GridDuck issued Client ID and Client Secret. The application will have access to all resources which the authorised user has access to within the scopes dictated when the application is created. This is called the client credentials grant.

For now this is the only authorisation grant approved for third party use. In the near future the implicit and authorization code grants will be available which will allow third party applications which any user of GridDuck can utilise.