On This Page:
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.
8.2. Key Aspects:
There are 4 key aspects to using the API:
8.2.1. Resource IDs (URIs) [details]
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:
8.2.2. Uniform Methods [details]
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:
(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.
8.2.3. Resource Representations [details]
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.
8.2.4. Authorization [details]
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: