Home › Specification › Draft 1.0 Specification version 1

Connector API - Draft Specification 1.0 version 1

Mon, 09/29/2008 - 14:29 — rossfsinger

The Jangle connector is an application that translates the back-end business logic, data models, relationships and workflows into the Jangle entities. In version 1.0, connectors must be REST based and follow the URI structure of standard Jangle resources (although the resources themselves can have a different name locally, see the section on connector service responses for more information). All responses are a combination of HTTP status codes and JSON data structures.

There are four kinds of responses a Jangle connector may return:

  1. Services: An explanatory response of the entities available in the connector, the paths to those entities, whether or not an entity is searchable, what kinds of mime-types are accepted in POST and PUT operations and what category filters can be used with a particular entity.
  2. Feed: A paged list of resources. Can include the relationships between resources and links to alternate metadata formats available.
  3. Explain: Analogous to an OpenSearch Description Document but also contains elements found in an SRU Explain response.
  4. Search: Basically identical to a feed response, a search response allows a Jangle core to return the results using OpenSearch extension elements.

All Jangle connectors must return a services response at {base_url}/services/.

Jangle connectors should not define absolute URLs internally, since it is possible that the same connector could be used by multiple Jangle cores (which, in turn, would mint different URIs for the same resource). Instead, connectors should be written to expect an HTTP Request header, $HTTP_X_CONNECTOR_BASE, to be sent by the Jangle core, and use that to construct absolute URIs. In the absence of this header, it is permissible for a connector to send a relative URI.

While connector paths do not have to conform to Jangle entity names, the URIs they create do, so if "actors" is mapped to /borrowers/ and "items" is mapped to /holdings/, URIs would still need to be returned as /actors/{id}/items/ and not /borrowers/{id}/holdings/.