Changes between Version 1 and Version 2 of API
- Timestamp:
- 05/31/09 19:35:02 (16 months ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
API
v1 v2 6 6 7 7 == Introduction == 8 The communication wiki:API is used by ''components'' to communicate with !GoodRobot.com server, for controlling a remote Robot or a robot to receive control inputs. wiki:Componentsare 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.8 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. 9 9 10 10 == Usage Scenario == … … 12 12 This API is used while both sending data from a component to the !GoodRobot.com and receiving data from the !GoodRobot.com server. 13 13 14 This wiki: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, is described [wiki:ReportsAPI here].14 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]. 15 15 16 16 == Protocol == … … 18 18 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. 19 19 20 As per the !GoodRobot wiki:API, components act as the client and thus initiating the transaction with the !GoodRobot.com server. wiki:Components needs to use PUT or POSTmethod 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.20 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. 21 21 22 22 The URI, passed in the HTTP message, will have these specific information: … … 57 57 == Security and Authentication == 58 58 59 For enhanced security, all wiki:Componentsneed 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.59 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. 60 60 61 61 There are two modes of key based authentication that is used: … … 63 63 b. a signature key (which is a digital signature, based on the public/private key pair, signed using the contents) 64 64 65 wiki:Componentscan 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.65 [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. 66 66 67 67 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.
