Docs Menu

Introduction

Platform overview

The Internet of Things (IoT) is a technology market that is set to explode in the coming years. Although estimates vary, analysts place the market size in the hundreds of billions to trillions of US dollars by 2020. With this potential market size, it is little wonder that many existing and startup companies are focusing on IoT products.

 

But IoT brings with it new technological challenges - or at least the merging of existing challenges. By definition the IoT connects embedded devices both to other embedded devices and back-end servers via the internet. Data is exchanged over these connections with a view to bringing the “smart” to IoT - whether that be collaborative functionality between two devices or large scale server side data analysis to inform operation. This exchange of data requires two key technologies: cloud based infrastructure to bridge the communication and a common communication protocol set.

 

The cloud based infrastructure allows devices and servers on different networks to communicate securely - specifically by providing a mechanism to securely traverse NATs and firewalls. The common communication protocol set allows the embedded devices and servers to exchange data in a way that both parties can understand.

 

Embedded devices and servers typically don’t use the same protocol. Leading the charge on the server side is the now ubiquitous HTTP. While on the embedded side MQTT is the favoured protocol. Collectively, MQTT and HTTP - as well as a translation between the two - make up the common communication protocol set used for IoT communication.

 

Building this communication infrastructure and communication protocol set can be both a time consuming and resource intensive task. Not to mention the requirement to have both embedded and server side developers on your team.


Golgi is a platform that aims to resolve this issue for IoT developers. Golgi provides code generation for embedded devices as well as a hosted web service. The combination of generated embedded code and web service allows developers to expose the functionality of their embedded device via a custom API as well as access other existing APIs from the embedded device. Whether you want to read the temperature sensor attached to your embedded device remotely, periodically upload that temperature data directly to a third-party data storage/analytics API or even send out an SMS with third-party SMS API, Golgi will provide all the code and connections that you need.

Platform architecture

The Golgi architecture is made up of your embedded devices and your web service (hosted by Golgi). The architecture is connected to HTTP clients requesting data from your embedded devices as well as HTTP servers accepting data/requests from your embedded devices.

Developers can define what data their embedded devices expose via their API (methods) as well as the third-party APIs (connectors) that their embedded device want to access via Golgi’s developer portal. Once your methods and connectors are defined, the developer portal can generate embedded code for Arduino and Arduino like (MediaTek, Intel Edison, Intel Galileo) platforms as well as build, launch and manage your hosted web service. The embedded code can be downloaded and integrated into your Arduino project.


Once both your embedded device and hosted web service are running you will be able to access your device's functionality from anywhere using HTTP.

Developer Guide

Create your account

To sign up for Golgi go to https://www.golgi.io and click the “Join Golgi” button.

 

Our Business Development team will then get in touch to create your account and help you get started with Golgi. Once your account is created, you will receive an activation email. Just click on the link and you will brought to a page to set your password. Once you set your password you are signed up as a Golgi developer!


You can now log in and start using Golgi. Go to www.golgi.io to access the developer portal.

Configure your Golgi Account

Signing into the Golgi Developer Portal will present you with your own developer home screen:

Your home screen has three main sections “Golgi Developer Details”, “Golgi Usage/Limits” and “Registered Applications”.

 

The “Golgi Developer Details” section has four key values: “Name”, “Email Address”, “Account Type” and “API Root”. The “Name” and “Email Address” fields refer to your registered name and email address respectively. The “Account Type” field describes your Golgi account type - see Golgi’s pricing page for a description of account types. The “API Root” field is the subdomain of the golgi.xyz domain where all of your APIs can be accessed - for example if your “API Root” is “great-apis” your APIs will be available from “great-apis.golgi.xyz”. We’ll discuss how individual APIs are accessed later in the documentation.

 

The “Golgi Usage/Limits” section has three fields; “Period Begin”, “Users” and “Volume”. “Period Begin” states the date of the beginning of the current billing/usage period, “Users” states the number of registered devices that you have and “Volume” specifies the amount of data that you have transmitted.


The “Registered Applications” section lists all Applications/APIs that you have created in your Golgi account. Each element in the list consists of the name of the API as a clickable link - following the link brings you to the details of the API.

Creating your API

Now that you are familiar with your homepage let’s look at an application page. Click the “Add Application” button to create an application. By default it will be created with the name “New Application”. Click the “New Application” link to navigate to the Application/API details.

 

 

 

The Application page has two sections. The first contains the “Application Name”, “API Domain” and the “API Access Key”. The “Application Name” field is used as an identifier to you the developer. Choose an appropriate name for your Application so that as your list of Applications grows you can find any of them at a quick glance.

 

The “API Domain” field is used to specify which API a user of your APIs is trying to access. Earlier we saw that your “API Root” is used to specify a URL for all of your APIs; an “API Root” of “great-apis” means that all of your APIs will be accessed using the URL “great-apis.golgi.xyz”. You can access a specific API by adding the “API Domain” as the root of the URL path; an “API Root” of “great-apis” and an “API Domain” of “temp” would be accessed with the URL “great-apis.golgi.xyz/temp/<method-name>” - we’ll discuss what is required for the <method-name> portion of the URL later in the documentation.

 

The “API Access Key” is the key used in the API calls to authorize those calls, this is the main method of authorization to your published API.

 

The second section of the Application page - “API Definition” - contains the description of your API; this definition contains the API that you want to expose from your embedded device (methods) and the third-party APIs that you want your embedded device to be able to connect to (connectors). We’ll discuss the format of an API Definition in the next section.

 

The last section “Embedded Source Code Generation” allows developers generate embedded code for their board of choice.

 

The list of supported boards includes:

  • Arduino

    • Arduino with Ethernet Shield

    • Arduino with WiFi Shield

  • Intel

    • Intel Edison using WiFi

    • Intel Galileo Gen 2 using Ethernet

  • Mediatek

    • MediaTek LinKit One using WiFi

    • MediaTek LinKit Assist 2502 using WiFi

  • Other

    • Generic Code requiring a custom IP shim for connectivity

 

With your “API Definition” completed you can select a board from the available list and click the “Generate Embedded Code” button. A progress bar showing the progress of the generation will be displayed. Once the generation is complete you will be offered the option to download the generated code.

 

In the tar file are 3 files :

  • Example-Stuff.cpp

  • libgolgi.h

  • libgolgi.cpp

 

The files libgolgi.cpp and libgolgi.h contain all the code you will require to build out your embedded devices functionality. As the name suggests, the file Example-Stuff.cpp provides sketch example code.

 

Design your API

Golgi APIs are specified in the API definition window of an application. This definition uses a language neutral syntax that can be processed by Golgi’s code generator to produce code for your embedded devices as well as generating your custom Golgi web service. The description file has four main descriptors; struct, exception, method and connector.

struct

A struct can be thought of as similar to a C style struct. A convenient way of grouping together related items. Structs are built up from the base types (i32, string, double and data), other structs and lists of base types or other structs. The base types and lists map to values:

 

  • i32: a 32-bit signed integer,

  • string: a text or binary string,

  • double: a 64-bit floating point number,

  • data: a blob (Binary Large Object) that encapsulates variable length binary data

  • list: an ordered list of elements which may contain duplicates.

 

struct DemoStruct {
    i32 integer_value;
    string text_value;
    double double_value;
    data data_blob;
    list integer_list;
}

 

 

In this demonstration struct we have five items, an i32, a string a double, a data entry and a list of i32s. Each item is specified using the syntax:

 

 ;

 

The “item type” is a base type, struct or list of base types or structs. The “item variable name” is the name you will use to access this variable in your embedded code.


It is worth noting that you must specify structs in order; that is, if you want to use StructA as an item in StructB you must specify StructA before StructB in the API definition.

exception

Exceptions are almost identical to structs except that they are specifically used to transmit an exception/error state - a successful call to your API might return a struct whereas a failed call would return an exception. Being able to specify exceptions gives developers complete control over the error information they want to return to a user. The declaration of an exception differs from the declaration of a struct only in the declaration specifier; exception declarations use the exception (as opposed to the struct) specifier.

exception DemoException {
    i32 integer_value;
    string text_value;
    double double_value;
    data data_blob;
    list integer_list;
}

method

Method definitions specify the methods your API will expose, for example:

methods {
    void DemoMethod1(DemoStruct ds) throws(DemoException dex);
    DemoStruct DemoMethod2(DemoStruct ds) throws(DemoException dex);
    DemoStruct DemotMethod3();
}

 

As was the case for structs and exceptions the declaration starts with the “methods” keyword. The methods are specified using the following syntax:

 

<return type> <method name>(<list of args>) [throws(<list of exceptions>)]


where and have the format , ,... The types in can be any base type or previously defined struct and the types in can be any previously defined exception.

 

connector

Connectors are similar to methods but provide a simple interface to some popular web services such as Twillo SMS or Zapier. This allows for example your embedded IoT device to send an SMS via Twillio. The format of a Twillio connector for is ..

connector TwilioSMS{
    params/device: To,Body;

    params/constant: From = +16502001951;
    params/constant: Sid = AC673a216fcbbcd37a7ad4bf25e886fb0e;
    params/constant: Token = 613a2dfda4b0ceed0e72c1c94d25f461;

    argument/form: To,From,Body,Sid,Token;

    url: https://api.twilio.com/2010-04-01/Accounts/__/Messages.json;
    auth/basic: Sid,Token;
    response/json: sid,date_created,date_updated,
                   date_sent,account_sid,to,
                   from,body,status,num_segments,
                   num_media,direction,api_version,
                   price,price_unit,error_code;
}

Deploying your API

Once specified in your “API Definition” you can build and launch a web service to host your API. Click the “Hosted WEB API Console” button below your “API Definition” to navigate to Hosted API Console. The console displays four values; “Application Name”, “API Domain”, “Running Instances” and “Public IP”. The “Application Name” is simply the name you assigned to this application, the “API Domain” is the URL and path where your API can be accessed. The “Running Instances” is the number of instances of your hosted web service that are currently running and “Public IP” is the IP address where an instance (if any) is running.

 

Below this are five buttons “Stop API”, “Start API”, “Build Image”, “Build Local Image” and “Rolling Update”. The “Stop API” button will stop any instances that are running, the “Start API” button will start a running instance, the “Build Image” button will build an image for your hosted web service based on your current “API Definition” and “Rolling Update” will stop a currently running instance and replace it with the latest built image.


Once you have an instance running you can test its functionality using the “API Test/Debug Facility” button. This button will bring you to your APIs test page which will show a list of the API methods you have defined including their names as a clickable button, their request type (HTTP Verb) and their return type. Click a “Method Name” button load the method’s test screen. On the method test screen you can fill out the required parameters, send a test request and view the response.

Debug and Troubleshoot

The “API Test/Debug facility” button allows calling methods in your published API directly as if they were coming from a client. The following describes what you would see based on the HiLo example.

 

When you click on the API Test/Debug Facility, you will  see the following page

 

 

In the  “Call Target” field you put the unique destination name , as described in the HiLo example , the embedded device was given a unique id in code at registration called “my-arduino-device”, this is the value we will see here as this is the target for which this “client” wishes to send data. The field Name led.value is the i32 value we want to send to the target as defined in the API definition. In this case a value of zero means for the embedded device to switch off the led and 1 to switch it on. After filling in the required fields the dialog color changes to green from red to indicate we can now send an API request

 

 

Choosing the “Show Call Details” button, we see the HTTP Method – POST, the URL and the POST Body.

 

 

Pressing the “Call API” button will simply execute the API request for which we will see the result, “SUCCESS” or “FAILURE”.

 

The JSON output looks like  

 

Another feature of the debug domain is you can paste the API domain into your browser and see information about the iamge created to host the published API definition          

 

Image Created: Wed  7 Oct 08:21:43 UTC 2015

 

To see the API structure, you can use /.svcmap in your browser

 

Sample output:

{ 
    "methods": [
        {
            "namespace": "HILO",
            "service": "Hilo",
            "name": "setLed",
            "voidResult": 1,
            "voidArg": 0,
            "resultType": "void",
            "exceptions": [
                { "name": "GolgiException"} 
            ]
        }
    ]
}

 

Also further information about parameter types ..    /.typemap give us :

{
    "types": [
        {
            "errText":{
                "optional":1,
                "isList":0,
                "type":"GolgiString"
            },
            "errType":{
                "optional":1,
                "isList":0,
                "type":"GolgiInteger"
            },
            "__name":"GolgiException",
            "__keys":["errText","errType"]
        },
        {
            "value":{
                "optional":0,
                "isList":0,
                "type":"GolgiInteger"
            },
            "__name":"Led",
            "__keys":["value"]
        },
        {
            "led":{
                "optional":0,
                "isList":0,
                "type":"Led"
            },
            "__name":"Hilo_setLed_reqArg",
            "__keys":["led"]
        },
        {
            "internalSuccess_":{ 
                "optional":1,
                "isList":0,
                "type":"GolgiInteger"
            },
            "golgiException":{
                "optional":1,
                "isList":0,
                "type":"GolgiException"
            },
            "__name":"Hilo_setLed_rspArg",
            "__keys":["internalSuccess_","golgiException"]
        }
    ]
}

Getting Started

HiLo World

The HiLo World API demonstrates the most basic of IoT project functionality, turning on and off an LED. The state of the LED is usually controlled by some local input. In Golgi’s case that control will be handled by a Golgi hosted web API.


The API definition is the starting point for defining the HiLo World example. Begin by creating a new application in the Golgi portal, assigning it the name “HiLo World” and  configuring your API domain to be “hilo-world”. Then copy and paste the following API definition into the “API definition” box

 

 


struct Led 
{
    i32 value;
}

exception DemoException 
{
    i32 integer_value;
}

methods 
{
    void setLed(Led led) throws(DemoException dex);
}

 

The HiLo World API Definition specifies the essential data used to control the LED. Specifically, it creates an Led data structure that has a single field; an i32 named value. This value will be used to specify whether the LED should be on, a value of 1, or off, a value of 0. Next is a definition of the methods with a single method, setLed. The setLed method takes a single argument, an Led data type, which will contain information as to what state (on/off) the LED should be set to.

 

With the API Definition specified you are ready to generate the code for your Arduino (or other supported) board. Select the type of board you are using (for the purposes of this tutorial we chose Arduino) and choose either BLE, Ethernet or WiFi depending on supported interfaces for your board and which one you want to use to connect to the Internet.

 

Next click the “Generate the Embedded Code” button; this will bring up a progress bar while the code is being generated. When the generation is complete a download button will appear to get the tar file containing the generated code; click on this now.

 

After unpacking the downloaded tar file you should see the following three files:

 

  • Example-Stuff.cpp

  • libgolgi.h

  • libgolgi.cpp

 

The Example-Stuff.cpp sketch contains all the code needed for your Arduino device to receive requests to switch on/off your Arduino LED. The file libgolgi.h is included in the HiLo.ino file and in turn uses libgolgi.cpp.The .ino file is the main file needed,  here you will find the familiar Arduino loop() and setup() functions which you can add to as normal.


Looking more closely at the Example-Stuff.cpp generated sketch file, the loop() function contains a call to GolgiService() which should not be removed, this allows the arduino to check if there are incoming messages on the Golgi interface. In the setup() function there are two code snippets to be looked at, the first is the setting up of the ethernet device as follows

 

// For Ethernet setup

// set a mac address
static byte ethernetMac[] = { 0xXX, 0xXX, 0xXX, 0xXX, 0xXX, 0xXX };

// setup the Ethernet shield
if(Ethernet.begin(ethernetMac) == 0)
     {
        Serial.println("FAILED");
        Serial.println("Couldn't setup Ethernet");
        while(true);
    }

This function attempts to set up the Ethernet interface and reports if there is a failure.

 

The second code snippet is the call to GolgiSetup() where you register your id. The devices Golgi id is an identifier that allows other devices to address your Arduino board. For example, when your mobile application sends a HTTP request to switch on/off your LED then this id will be the id of the device to be addressed. Using Golgi ids allows for multiple IoT devices to exist in your system and to be addressed individually.


Note that a requirement of Golgi ids are that they are unique within the API; i.e. you can not register two devices with the id “my-arduino-device” in a single API.

.

 

// For Ethernet shields
  GolgiSetup("my-arduino-device");

// For WiFI Shields
GolgiSetup("my-arduino-device",
                  "WIFI-SSID",
                  "WIFI-PASS");

 

Inbound requests to the Arduino board are handled via the class “DemoSetLedHandler” which is a name derived from the service name (Demo) and the method name (setLed). In order to be able to receive requests add the following line of code to the setup() function.

 

(new DemoSetLEDHandler())->registerReceivers();

 

This creates a new instance of the DemoSetLEDHandler class and calls its registerReceivers() method. This registers the created DemoSetLEDHandler() object as the handler for inbound setLED requests. Specifically, inbound setLED requests are handled by the setLEDHandler::inboundSetLed() method. Within this method, the request data sent in the HTTP request can be accessed within this method via the argument “Demo_setLed_reqArg”. The “Demo_setLed_reqArg” wraps the “Led” struct we defined in the API Definition so to access the “value” passed using the following call:

 

Demo_setLed_reqArg->getLed()->getValue();

 

Based on the value contained in “value” we can choose to switch on or off the LED; specifically, 1 for on and 0 for off.


After we have processed the request we will want to send a result to the sender. The “setLed” method was defined with a void return type, which means we can only return success or an instance of the default exception, GolgiException. Sending results is facilitated by the “DemoSetLedResultSender *resultSender” argument that is passed to the  “inboundSetLed” method. To send a successful response use call the “success” method of the “resultSender”.

 

resultSender->success();

 

To send a GolgiException start by creating the Exception and then send it with the “failWithGolgiException” method of the “resultSender”

 

GolgiException *golgiException = new GolgiException();
// set the appropriate fields in golgiException for this error scenario
resultSender->failWithGolgiException(golgiException);

To send the user defined exception HiLoException then send it with the failWithHiLex() method of the resultSender

HiLoException *hlex = new HiLoException();
            // set the appropriate fields in hlex for this error scenario
            resultSender->failWithHlex(hlex);

 

If you have defined the return type of your method to be something other than “void” (for example, string, i32 or a struct) the ResultSender’s success method will expect that type as an argument.

 

Complete Sketch

// Golgi Ethernet Shield Initialisation 
// 
// Replace the six 0xXX values with the MAC address of your Ethernet
// Shield which should be printed on its underside
//
 
#include "Arduino.h"
#include "SPI.h"
#include "Ethernet.h"
#include "libgolgi.h"

#define LED_PIN   3

static byte ethernetMac[] = { 0xXX, 0xXX, 0xXX, 0xXX, 0xXX, 0xXX };

//
// Class to handle inbound setLed
//
class DemoSetLedHandler : DemoSetLedRequestReceiver
{
public:
    DemoSetLedHandler()
    {
        Serial.println("Initialise output pins");
        pinMode(LED_PIN, OUTPUT);
        digitalWrite(LED_PIN, LOW);    
    }

    void registerReceivers(void)
    {
        DemoRegisterSetLedRequestReceiver(this);
    };

    void inboundSetLed(DemoSetLedResultSender *resultSender, Demo_setLed_reqArg *arg)
    {
        bool allOk = true;  // Just hardcoding this here to all ok and return success to sender

        // Dereference the arg pointer to access the passed in argument values
        Serial.print("Set LED to value: ");
        Serial.println(arg->getLed()->getValue());
        if(allOk)
        {
            // Toggle the LED based on the incoming
            if (arg->getLed()->getValue() == 1)
            {
                digitalWrite(LED_PIN, HIGH);
            }
            else 
            {
                digitalWrite(LED_PIN, LOW);
            }
            resultSender->success();
        }
      else if (failureScenario1)
      {
        GolgiException *golgiException = new GolgiException();
        // set the appropriate fields in golgiException for this error scenario
        resultSender->failWithGolgiException(golgiException);
        delete golgiException;
      }
      else
      {
            HiLoException *hlex = new HiLoException();
            // set the appropriate fields in hlex for this error scenario
            resultSender->failWithHlex(hlex);
            delete hlex;
      }
    };
  
~DemoSetLedHandler(){}   // Destructor 
};

//
// Class to handle outbound setLed
//
class DemoSetLedSender : DemoSetLedResultReceiver
{
public:
    DemoSetLedSender(char *_dst, Led *led)
    {
        //
        // Create the argument structure and send
        //

        Demo_setLed_reqArg* _arg = new Demo_setLed_reqArg();
        _arg->setLed(led);
        DemoSetLed_sendTo(this, _dst, _arg);
        delete _arg;
    }

    void success(DemoSetLedResultSender *res)
    {
        //
        // Handle successful result
        //
       Serial.println(“Success”);
        delete this;
    }

    void failWithGolgiException(GolgiException *golgiException)
    {
        //
        // Handle error result
        //
Serial.println(“failWithGolgiException : ” + String(golgiException->getErrType()) + “/” + String(golgiException->getErrText()));
        delete this;
    }
    void failWithHlex(HiLoException *hlex)
    {
      //
      // Handle error result
      //
      delete this;
    }
};
setup()
{
    Serial.begin(9600);
    Serial.print("Setting up Ethernet: ");

    if(Ethernet.begin(ethernetMac) == 0){
        Serial.println("FAILED");
        Serial.println("Couldn't setup Ethernet");
        while(true);
    }
    Serial.println("SUCCESS");

    GolgiSetup(“my-arduino-device”); 

     Serial.println("Setup Request Receiver For LED transaction");
    (new DemoSetLedHandler())->registerReceivers();
}

//
// To perform Golgi housekeeping (network connections and the like) then
// you need to call GolgiService() in your loop() function
//
loop()
{
    GolgiService();
}

 

The sketch can now be uploaded to your board with the arduino IDE

 

Arduino/MediaTek/Intel Reference

Ethernet Shield

static byte ethernetMac[] = { 0xXX, 0xXX, 0xXX, 0xXX, 0xXX, 0xXX };

Ethernet.begin(ethernetMac)

Returns 0 on successful ethernet setup, otherwise “Not yet setup” is indicated

 

void GolgiSetup(char * registrationIdString)

Call to set up golgi resources and initialize this device with the registrationIdString

WiFi Shield

GolgiSetup(char * registrationIdString, char * wifiSsid, char * wifiPass );

Call to set up golgi resources and initialize this device with the registrationIdString , wifi ssid and wifi password.

All Boards

void GolgiService(void )

Call to check the golgi interfaces for incoming data or process outgoing data, should be called within the Arduino loop() function.

API Definitions and their generated classes

The generic format of a method within the API definition is

 

(arg1Type arg1, arg2Type arg2, ……)

which generates for inbound message handling the following class

 

class MethodNameHandler : MethodNameRequestReceiver
{
    MethodNameHandler()
    {
    }
    void registerReceivers(void)
    {
        RegisterMethodNameRequestReceiver(this);
    };
    void inboundMethodName(MethodNameResultSender *resultSender,
MethodName_reqArg *arg)
    {
    };
~MethodNameHandler(){};
};

.. for outbound handling the following class is generated 


class MethodNameSender : MethodNameResultReceiver{
public:
    MethodNameSender(char *_dst, Led led){
        //
        // Create the argument structure and send
        //

        MethodName_reqArg* _arg = new MethodName_reqArg();
        _arg->MethodName(led);
        MethodName_sendTo(this, _dst, _arg);
        delete _arg;
    }

    void success(MethodName *res){
        //
        // Handle successful result
        //
        delete this;
    }

    void failWithGolgiException(GolgiException *golgiException){
        //
        // Handle error result
        //
        delete this;
    }
};

API HTTP Access Reference

Accessing your API from a HTTP client requires a correctly formatted request. This means the request must:

 

  • include the correct URL and path

  • include a destination embedded device

  • include the relevant access code

 

Golgi API URLs and paths

As we saw earlier in the documentation the URL and path root for accessing your API is constructed from the “API Root” associated with your developer account, the “API Domain” associated with your Application and the API method you are trying to access. The URLs and paths have the format: <API Root>.golgi.xyz/<API Domain>/<method name>.


As an example, if we have an “API Root” of “great-apis”, an “API Domain” of “temp” and a method name of “inCelcius”, the URL and path to be addressed would be great-apis.golgi.xyz/temp/inCelcius.

Device destination address

Every embedded device in Golgi registers with a unique Golgi id; this id allows API requests to be addressed to a specific embedded device. The address of the embedded device that you wish to address is passed as a URL parameter in the HTTP request. Specifically, your request should include a “dest=<destination Golgi id>” parameter. As an example, if the device you wish to address has registered with an address of “my-arduino-device” (as we did in the HiLo World example) a request must include a “dest=my-arduino-device”

Token Authentication

Golgi by default uses token authentication to authenticate users of APIs. In each of your APIs you will have an “Access Key”. This key should be provided to users of your API to allow them to access your APIs resources. Requests to your API should include this Access Key in an “Authorization” HTTP header. For example:

 

Authorization:

An example HTTP request and response for Token Authentication is shown below.

 

Request:

POST /domain/setLed?dest=my-arduino-device HTTP/1.1
Host: root.golgi.xyz:8888
Content-Length: 46
Content-Type: application/json
Authorization: 55eefde6425e800009000001cc54b785da0e4a8279e2663ed87cdb3b
{
    "Led": {
        "value": 1
    }
}

 

Response:

HTTP/1.1 200 OK
Date: Fri, 02 Oct 2015 10:44:24 GMT
Content-Type: application/json
Content-Length: 46
Access-Control-Allow-Credentials: true
Access-Control-Allow-Origin: *
Server: nginx
X-Ratelimit-Limit: -1
X-Ratelimit-Remaining: -1
X-Ratelimit-Reset: 1443798480

 

HMAC Authentication

An alternate authentication mechanism is HMAC authentication. HMAC authentication allows requests to the API to be authenticated without transmitting the secret access key. Golgi uses HMAC-SHA1 signing in the following way:

 

  1. Create a date string with the following format: “Fri, 02 Oct 2015 12:24:02 GMT”,

  2. Add this date string as your “Date” HTTP header,

  3. Create the string to sign. This string should be “date” followed by a colon and then a URL encoded form of the date string from Step 1. For example, “date:Fri%2C+02+Oct 2015+12%3A24%3A02+GMT”,

  4. SHA-1 encode the string from step 3 using your “HMAC Secret Value”,

  5. Base64 encode the SHA-1 signed string from step 4,

  6. URL encode the Base64 string from step 5,

  7. Add a HTTP header to your request with the form: “Authorization: Signature keyId=”<key_id>”, algorithm=”hmac-sha1”, signature=<HMAC Signature>


An example HTTP request and response for Token Authentication is shown below.

 

Request:

POST /domain/setLed?dest=my-arduino-device HTTP/1.1
Host: root.golgi.xyz:8888
Date: Fri, 02 Oct 2015 13:49:50 IST
Content-Length: 46
Content-Type: application/json
Authorization: Signature keyId="55eefde6425e800009000001cc54b785da0e4a8279e2663ed87cdb3b
", algorithm="hmac-sha1", signature="L3kfWBq6bfIbNEkpJ8o8KKHrkNI%3D
"

{
    "Led": {
        "value": 1
    }
}

 

Response:

HTTP/1.1 200 OK
Date: Fri, 02 Oct 2015 13:49:56 GMT
Content-Type: application/json
Content-Length: 46
Access-Control-Allow-Credentials: true
Access-Control-Allow-Origin: *
Server: nginx
X-Ratelimit-Limit: -1
X-Ratelimit-Remaining: -1
X-Ratelimit-Reset: 1443798480

Testing HTTP Access

Once you have an instance of your API running you should be able to access it’s testing page. This can be accessed by clicking the “API Test/Debug Facility” button that is found on the “Hosted API Console” page of your API. The button launches the page <API Domain>.golgi.xyz/<API Root>/.test. Once there you can see all available API methods and send test requests for each one.


The test page for the “HiLo World” example should look like:

 

 

You can click the “setLed” button to bring up a web page that will allow you to send a test request to set the LED.

Request:

POST /hilo/setLed?dst=mt-board HTTP/1.1

Host: golgi-dev.golgi.xyz

Connection: keep-alive

Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8

Upgrade-Insecure-Requests: 1

User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/46.0.2490.71 Safari/537.36

Accept-Encoding: gzip, deflate, sdch

Accept-Language: en-US,en;q=0.8

Content-Type: application/json

Content-Length: 23  

 

{

   "led":

    {

       "value": "1"

   }

}

 

Response:

HTTP/1.1 200 OK

Content-Type: application/json

Date: Fri, 25 Sep 2015 13:52:55 GMT

Transfer-Encoding: chunked

 

{

   "success": 1

}

Technical FAQ

Q. I’m a developer where do I start?

  1. Firstly you need to  sign up for Golgi, go to https://www.golgi.io and click the “Join Golgi” button. Our Business Development team will then get in touch to create your account and help you get started with Golgi.

 

Q. How does Golgi work?

  1. Golgi provides a transport and API publishing infrastructure to IoT devices.The idea is to allow easy access and control of IoT devices via a published API, this allows any other device to connect via standard HTTP requests. Nearly all devices mobile, web etc can access HTTP web interfaces easily.


 

Q. How is the Golgi platform architected?

  1. Embedded devices connect to a hosted web interface which in turn can accept connections via HTTP requests secured via an API key which is generated in the Golgi developers portal.

 

Q. How do I access the developer portal?

  1. Simply go to https://devs.golgi.io/ and sign in with your username and password, here you can view  your application's data, like it’s API definition as well as viewing statistical data for each app. In the portal you can also upgrade your package and access our forum and bug reporting tool.

 

Q. What embedded platforms are currently supported?

  1. At the moment the following devices are supported

 

  1. Arduino

  1. Arduino with Ethernet Shield

  2. Arduino with WiFi Shield

     B. Intel

  1. Intel Edison using WiFi

  2. Intel Galileo Gen 2 using Ethernet

    C.Mediatek

  1. MediaTek LinKit One using WiFi

  2. MediaTek LinKit Assist 2502 using WiFi

 

Q. How do I found out about downtime?

 

Q. Where can I file a bug report?

  1. When you log in to the developer portal, click on the “Bug Reporting” link on the left hand side of the dashboard.

 

Q. How do I access the community discussion forum?

  1. When you log in to the developer portal, click on the “Discussion Forums” link on the left hand side of the dashboard.

 

Q. How do I delete my account?

  1. Please contact the Golgi support team to delete your account

 

Q. Is it possible to have an on premise solution?

  1. This is currently not envisaged but please contact the Golgi support team for further details

 

Q. Where can I access Golgi sample code?

  1. There are several client side examples available on our GitHub account at GolgiDevs