HELP TOPIC: "8. REST API – Overview"

We are beginning an incremental deployment of a Genboree Application Programming Interface (API) that exposes the data entities represented within Genboree and also allows authorized users to modify stored data.

The API is based on REST principles and a Resource Oriented Architecture (ROA). This approach greatly simplifies the interface and results in predicatable consistency. We believe this also makes the learning curve less steep, compared to more 'involved' alternatives for web-services.

The API is currently being being used both by collaborators and internally. Non-Genboree users with programming skills have written scripts that assist or automate certain Genboree tasks and created their own user interfaces that use Genboree via Ajax.

We will continue to expose more Genboree entities, as well as expand method support for new and existing resources.

Data entities stored within Genboree are exposed as resources, which have a unique resource identifier (URI). Genboree resource identifiers are in fact web URLs; each URL is the location of a specific resource which you want to access, modify, or delete. Resources can be single data items or a collection (list) of multiple items.

The URLs have a general form:

• - {genbHost} is the host where Genboree is running (e.g. www.genboree.org)
• - {rsrcPath} is the path identifying the resource
  (e.g. /REST/v1/grp/{grpName}/db/{dbName}/tracks).
  • . This is like the path for a file on your computer; here, it is the path to get to a resource.
  • . The path points to a unique resource or a set of resources.
  • . It may not be the only path to that resource, however.
  • . Thus, the path provides some context to accessing the resource.
• - {rsrcParams} are any parameters for the resource, generally to modify the representation received or sent.
• - {authParams} are 3 required parameters Genboree uses to authorize and authenticate the user accessing/modifying the resource.

How can you operate on a resource? You'd like to be able to retrieve resources, create new resources and change existing ones, and possibly be able to delete existing resources. These fundamental operations map well to the standard HTTP methods:

• - GET to retrieve a representation of the resource.
• - PUT a new resource or a change an existing resource.
• - DELETE an existing resource.
• - POST (currently unused, but reserved for appropriate ROA-founded extension)

(If this seems similar to the 'CRUD' of relational databases, that's not surprising. Databases store resources and 'CRUD' encapsulates almost anything you'd want to do to a stored resource.)

Methods have return values which communicate the result of operation on the resource—generally success or type of failure. As is standard for REST APIs, Genboree leverages the standard HTTP response codes for this purpose.

In general, each resource has an appropriate representation whose default syntax is JSON. Genboree makes use of a standard wrapper for all JSON representations, to allow communication of the actual data and also of status information (mainly useful for troubleshooting). The status information supplements the aforementioned response code return values.

Some resources share representations, although many have specific representations.

Genboree must authenticate the identity of the person accessing/modifying the resource via the API, just as it requires login on its web site. Furthermore, Genboree must verify that they are authorized to retrieve or change the resource. To do this, ALL resource URIs must be appended with 3 parameters containing authorization information:

1. gbLogin the Genboree user name.
2. gbTime the current POSIX time (a.k.a. epoch time or UNX time)
3. gbToken computed as:
   SHA1({rsrcURI} + SHA1({gbLogin} + {userPassword}) + {gbTime})