= API = !GoodRobot API provides mechanisms to programatically communicate with !GoodRobot. [[PageOutline(2,, inline)]] == Introduction == The communication [wiki:API API] is used by ''components'' to communicate with !GoodRobot.com server, for controlling a remote Robot or a robot to receive control inputs. [wiki:Components 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 [wiki:API 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 [wiki:API API], is described [wiki:ReportsAPI 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 [wiki:API API], components act as the client and thus initiating the transaction with the !GoodRobot.com server. [wiki:Components 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 .. }}} == 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=), destination (dst=), format (format=) and action (action=). 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 [wiki:Components 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: a. fixed secret key (acts like a password) b. a signature key (which is a digital signature, based on the public/private key pair, signed using the contents) [wiki:Components 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 [wiki:GRAdmin 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.__''