API

GoodRobot API provides mechanisms to programatically communicate with GoodRobot.

  1. Introduction
  2. Usage Scenario
  3. Protocol
  4. Example of API
  5. Source and Destination
  6. URI Details
  7. Security and Authentication

Introduction

The communication API is used by components to communicate with GoodRobot.com server, for controlling a remote Robot or a robot to receive control inputs. Components are hardware or software units, that communicate with GoodRobot.com server and examples include a robot, web page, arduino with ethernet shield, special hardware that sends/receives control/sensor information, twitter and pachube front-end or any custom components that intends to integrate itself with the GoodRobot setup. The GoodRobot.com team will provide several components and allows third party to create custom components, provided they have the ability to integrate with GoodRobot.com using the API being described below.

Usage Scenario

This API is used while both sending data from a component to the GoodRobot.com and receiving data from the GoodRobot.com server.

This API is also used by programs that query the GoodRobot.com server for specific historical information, that is provided by GoodRobot.com server. The details of such historical or even current data, that is provided through this API, is described here?.

Protocol

The API is a RESTful interface. From Wikipidea, Representational state transfer (REST) is a style of software architecture for distributed systems such as the World Wide Web. REST, in itself, is not a protocol per se, but is a loose definition of how resources are defined and addressed. In simple words, REST can be loosely defined as sending and receiving XML data over HTTP interface.

As per the GoodRobot API, components act as the client and thus initiating the transaction with the GoodRobot.com server. Components needs to use PUT or POST method of HTTP protocol to send data and GET method of HTTP protocol to receive data. In most cases, the use of PUT method (which is used to send data) will also result in appropriate response, thus avoiding the necessity for an additional call to the GET method. The DELETE method is not used.

The URI, passed in the HTTP message, will have these specific information:

  • the source (the name of the sending component's instance)
  • the destination (the name of the receiving component's instance)
  • the data format and
  • the action.

It is also acceptable for a component or GoodRobot.com server to send the source and destination info as part of the data contents, rather than as URI parameters.

Example of API

Here is an example of API access. 

PUT http://www.GoodRobot.com/api/myrobot.web
Host: www.GoodRobot.com
Date: Fri Apr 10 13:16:35 GMT 2009
X-GoodRobotKey: Components_key_goes_here
..

<data>

<response>

Source and Destination

The source and destination indicates the names of the component instances (derived from the robot instance) that is sending the data and intended recipient respectively. Not in all cases, a component would know the destination component – such as a robot sending its movement and positional data to the GoodRobot.com server and may not have a specific destination (the GoodRobot.com server sends such data to appropriate destination or multiple destinations, depending on multiple parties requesting data). Hence while the source name is required, the destination name is optional.

It may be noted that the names of the source and destination are instance name of the component.

URI Details

The prefix for all HTTP requests will be  http://www.goodrobot.com/api/. This is followed by source (src=<value>), destination (dst=<value>), format (format=<eeml|csv>) and action (action=<value>). All parameters are optional in the URI (if source is not specified in the URI, it must be specified in the data contents). If destination and action is not specified, GoodRobot.com server will appropriately handle with default mechanisms. The default format is wiki:EEML.

Security and Authentication

For enhanced security, all Components need to authenticate themselves with GoodRobot.com server. Authentication is achieved by passing a special key to the GoodRobot.com server, which is used to authenticate the particular instance of a component. HTTP messages that fail authentication will be replied with '401 Unauthorized' response.

There are two modes of key based authentication that is used:

  1. fixed secret key (acts like a password)
  2. a signature key (which is a digital signature, based on the public/private key pair, signed using the contents)

Components can choose to use any one form of authentication key. In both cases, the key is passed as a custom HTTP header. In the case of fixed secret key, the header used is X-GoodRobotKey and in the case of signature key, the header used is X-GoodRobotSignature. In some rare cases, where the components do not have ways to send custom HTTP headers, they can pass the key as part of the URI – though this is deprecated.

The fixed secret key is created and maintained in the Admin? pages of GoodRobot.com server, for each instance of the component. The component needs to send the same exact key, as is maintained in the GoodRobot.com server. However, the fixed secret key method is not really a secure solution as someone could read the HTTP packets, which are sent in plain text. For those who wish to have a better solution, they can use SSL HTTP (“ https://” instead of “ http://”) to connect to the GoodRobot.com server.

For enhanced security, the signature key can be used, where the component needs to compute the signature for every HTTP message based on the URI, Date HTTP header and the contents of the message.

TBD - Details of how to compute this to be written later.