HOWTO build a Jangle connector
Note, everything here is negotiable. If you have a better idea for anything, please provide comments!
All GET requests should return a JSON object with the following keys:
time, string
UTC timestamp of request
request, string
returns the path and query string of the incoming request,
data, array
an array of objects,
Optionally, the response object may include:
links, hash
a hash of values to populate the link tags at the Atom feed level, such as for pagination.
Example:
links : { "self" : "\/actors\/", "first" : "\/actors\/", "last" : "\/actors\/?page=60"}
values can be either relative or absolute URIs
GET /actors/
Returns all actors associated with a given service. Can be paginated.
Actor objects should look like:
{
"updated":"2008-05-19T13:41:12-04:00",
"content_type":"text\/x-card",
"content":"BEGIN:VCARD\nVERSION:3.0\nN:Cubin;Barbara;;;\nFN:Barbara Cubin\nADR:;;1114 Longworth House Office Building;Washington;DC;20515;\nTEL;TYPE=work:202-225-2311\nTEL;TYPE=home:307-261-6595\nUID;TYPE=http:\/\/jangle.org\/terms\/#barcode:123458209\nUID;TYPE=http:\/\/jangle.org\/terms\/#URI:1866\nEND:VCARD\n",
"created":"2008-05-19T13:41:12-04:00",
"id":"\/actors\/1866",
"title":"Cubin, Barbara"
},
In this case the actor is being returned as a vCard, although other metadata formats could be used (like, for instance, FOAF). In order to meet the basic needs of Atom, the "title" element is being populated with the Actor's name. The ID is a relative URI in this example, although an absolute URI could also be returned (see this note on relative vs. absolute URIs for connector responses). The keys should mostly correspond to Atom elements. If "content" is being sent, either a content_type key/pair must also be sent, or the Jangle core will default to text/plain.
If alternate representations of the data are available, include a link key:
{
"updated":"2008-05-19T13:41:12-04:00",
"created":"2008-05-19T13:41:12-04:00",
"id":"\/actors\/1865",
"title":"Barrasso, John",
"link": { "http:\/\/jangle.org\/rel\/alternate#http:\/\/xmlns.com\/foaf\/0.1\/":
[
{
"type":"application\/atom+xml",
"href":"\/actors\/1865?record_format=foaf"
}
],
"alternate":
[
{
"type":"application\/atom+xml",
"href":"\/actors\/1865?record_format=foaf"
}
],
},
Jangle uses URIs for link types in an effort to specify with better granularity how to request a specific record type. This is legal in AtomPub. See here for more information.
The same applies for "related" links. For a given actor, you can also send:
{
"updated":"2008-05-19T13:41:12-04:00",
"created":"2008-05-19T13:41:12-04:00",
"id":"\/actors\/1865",
"title":"Barrasso, John",
"link": { "http:\/\/jangle.org\/rel\/related#items":
[
{
"type":"application\/atom+xml",
"href":"\/actors\/1865\/items"
}
],
"related":
[
{
"type":"application\/atom+xml",
"href":"\/actors\/1865\/items"
}
],
},
And this would return an Atom feed with the Items associated with a particular actor.
GET /actors/{id}
Returns an Atom feed with a single entry. The {id} parameter can also be a comma or semicolon separated list or a hyphen separated range. In these cases the feed will contain multiple entries (assuming all of the ids are valid). If the id or ids are all invalid, the connector should return a 404 error.
No "actor" relationships are explicitly defined except:
GET /actors/{id}/authenticate
This is optional and left to the whims of the connector developer as to how it works.
See Resource page for the distinction between Item and Resource.
The most obvious use case for the Item service at present is an availability service, although if write access is enabled, many more use cases can be seen (consortial borrowing, self-service checkout, renewals from discovery system, etc.).
For Jangle, a very simple availability specification has been created to easily include for display in external applications. See here for more information on simple_availability.
GET /items/
Returns all items associated with a given service. Can be paginated.
Item objects should look like:
{
"updated":"2008-05-19T15:10:50-04:00",
"links":
{
"related":
[
{
"type":"application\/atom+xml",
"href":"\/resources\/5426"
}
]
},
"created":"2008-05-19T15:10:50-04:00",
"summary":"checked in",
"id":"\/items\/000005951",
"title":"Available"
},
In this case the actor is being returned as simple_availability, although other
metadata formats could be used (like, for instance, ISO 20775). The title is very simple: "Available" or "Not Available" (for ease of display within clients). What these terms mean is at the discretion of the implementer (i.e. what is the availability for a non-circulating print journal?). The summary is a more detailed (but uncontrolled) description of the item's status.
The ID is a relative URI in this example,
although an absolute URI could also be returned (see this note on relative vs. absolute URIs for connector responses).
The keys should mostly correspond to Atom elements. If "content" is
being sent, either a content_type key/pair must also be sent, or the
Jangle core will default to text/plain.
Note the "related" link to the Resource this Item is associated with.
If alternate representations of the data are available, include a link key:
{
"updated":"2008-05-19T13:41:12-04:00",
"created":"2008-05-19T13:41:12-04:00",
"id":"\/items\/000005951",
"title":"Available",
"link": { "http:\/\/jangle.org\/rel\/alternate#info:ofi\/fmt:xml:xsd:iso20775":
[
{
"type":"application\/atom+xml",
"href":"\/items\/000005951?record_format=iso20775"
}
],
"alternate":
[
{
"type":"application\/atom+xml",
"href":"\/items\/000005951?record_format=iso20775"
}
],
},
Jangle uses URIs for link types in an effort to specify with better
granularity how to request a specific record type. This is legal in
AtomPub. See here for more information.
An example of a "Not Available" Item:
{
"updated":"2008-05-10T15:10:50-04:00",
"content_type":"text\/calendar",
"links":
{
"related":
[
{
"type":"application\/atom+xml",
"href":"\/resources\/5424"
}
]
},
"content":"BEGIN:VCALENDAR\nVERSION:2.0\nPRODID:-\/\/Ensemble Independent\/\/vPim 0.619\/\/EN\nCALSCALE:Gregorian\nBEGIN:VEVENT\nDTSTART;VALUE=DATE:20080510\nDTEND;VALUE=DATE:20080528\nSUMMARY:The Life and Correspondence of Sir Isaac Brock\nDESCRIPTION:checked out\nCREATED:20080606T155359\nLAST-MODIFIED:20080606T155359\nEND:VEVENT\nEND:VCALENDAR\n",
"created":"2008-05-19T15:10:50-04:00",
"summary":"checked out",
"id":"\/items\/000005950",
"title":"Not Available"
},
For unavailable items, send an iCal file to indicate when the item will be available again.
GET /items/{id}
Returns an Atom feed with a single entry. The {id} parameter can
also be a comma or semicolon separated list or a hyphen separated
range. In these cases the feed will contain multiple entries (assuming
all of the ids are valid). If the id or ids are all invalid, the
connector should return a 404 error.
The only "item" relationships are explicitly defined are to Resources:
/items/{id}/resources
Resource and Item are somewhat ambiguous in definition. It would perhaps be easier give an example of their relationship:
In a library catalog, the Resource would be the bibliographic record (in most cases what one would think of as a MARC record) or authority record of a given thing. The Item would be a particular instantiation of the Resource, like a circulating book with a barcode.
In an OpenURL link resolver, the Resource could be a journal or article and its metadata. The Item would be the particular holding (available in EBSCO Academic Search Premiere or DOAJ, for example).
Not all Resources would have Items, but Items would have to have a Resource (I think).
GET /resources/
Returns all resources associated with a given service. Can (and probably should) be paginated.
Resource objects should look like:
{
"updated":"2008-03-18T15:41:07-04:00",
"content_type":"application\/xml",
"content":"<record xmlns='http:\/\/www.loc.gov\/MARC21\/slim'><leader> Z 22 4500<\/leader><datafield tag='245' ind1='0' ind2='0'><subfield code='a'>Java in a Nutshell<\/subfield><subfield code='b'>A Desktop Quick Reference<\/subfield><subfield code='c'>David Lanagan<\/subfield><\/datafield><datafield tag='100' ind1='0' ind2='z'><subfield code='a'>Flanagan,
David<\/subfield><\/datafield><datafield tag='650' ind1='z' ind2='4'><subfield code='a'>Java<\/subfield><\/datafield><datafield tag='650' ind1='z' ind2='4'><subfield code='a'>Computers<\/subfield><\/datafield><datafield tag='650' ind1='z' ind2='4'><subfield code='a'>Programming<\/subfield><\/datafield><datafield tag='650' ind1='z' ind2='4'><subfield code='a'>Programming Languages<\/subfield><\/datafield><datafield tag='650' ind1='z' ind2='4'><subfield code='a'>Programming Languages<\/subfield><\/datafield><\/record>",
"author":
{
"name":"Flanagan, David"
},
"created":"2008-03-18T15:41:07-04:00",
"id":"\/resources\/2",
"title":"Java in a Nutshell"
},
In this case the resource is being returned as a MARC xml, although other
metadata formats could be used. In order to
meet the basic needs of Atom, the "title" element is being populated
with the Resource's title. There are cases where a Resource might not have a title, but something intuitive should be returned for standard Atom clients to display. The ID is a relative URI in this example,
although an absolute URI could also be returned (see this note on relative vs. absolute URIs for connector responses).
The keys should mostly correspond to Atom elements. If "content" is
being sent, either a content_type key/pair must also be sent, or the
Jangle core will default to text/plain.
If alternate representations of the data are available, include a link key:
{
"updated":"2008-03-18T15:41:07-04:00",
"links":
{
"http:\/\/jangle.org\/rel\/alternate#application\/marc21":
[
{
"type":"application\/atom+xml",
"href":"\/resources\/2?record_format=marc"
}
],
"alternate":
[
{
"type":"application\/atom+xml",
"href":"\/resources\/2?record_format=marc"
},
{
"type":"application\/atom+xml",
"href":"\/resources\/2?record_format=dc"
},
{
"type":"text\/html",
"href":"http:\/\/dilettantes.code4lib.org\/openbiblio\/shared\/biblio_view.php?bibid=2&tab=opac"
}
],
"http:\/\/jangle.org\/rel\/alternate#http:\/\/purl.org\/dc\/elements\/1.1\/":
[
{
"type":"application\/atom+xml",
"href":"\/resources\/2?record_format=dc"
}
]
},
"author":
{
"name":"Flanagan, David"
},
"created":"2008-03-18T15:41:07-04:00",
"id":"\/resources\/2",
"title":"Java in a Nutshell"
},
Jangle uses URIs for link types in an effort to specify with better
granularity how to request a specific record type. This is legal in
AtomPub. See here for more information.
The same applies for "related" links. For a given resource, you can also send:
{
"updated":"2008-03-18T15:41:07-04:00",
"link": { "http:\/\/jangle.org\/rel\/related#items":
[
{
"type":"application\/atom+xml",
"href":"\/resources\/2\/items"
}
],
"related":
[
{
"type":"application\/atom+xml",
"href":"\/resources\/2\/items"
}
],
},
"author":
{
"name":"Flanagan, David"
},
"created":"2008-03-18T15:41:07-04:00",
"id":"\/resources\/2",
"title":"Java in a Nutshell"
},
And this would return an Atom feed with the Items associated with a particular Resource.
GET /resources/{id}
Returns an Atom feed with a single entry. The {id} parameter can
also be a comma or semicolon separated list or a hyphen separated
range. In these cases the feed will contain multiple entries (assuming
all of the ids are valid). If the id or ids are all invalid, the
connector should return a 404 error.
No "resource" relationships are explicitly defined.
One of the advantages of Jangle is that it gives every discrete resource exposed a unique URI with a modicum of permanence.
However, the Jangle connector should not be expected to know the absolute URI of any of its resources, since that is at the discretion of the Jangle core application to manage. In fact, it's conceivable that a Jangle connector's resources could have multiple URIs for the same resource, if, for example, a connector is proxied by multiple Jangle core applications.
This means that a Jangle core must be able to handle both relative and absolute URIs in a connector response (since a connector response could refer to a resource defined in another service, which would need to be explicit).
It makes sense, then, that, for simplicity's sake: URIs to resources within a given connector should be relative (i.e. /resources/12345) and URIs external to a service absolute (i.e. http://jangle.org/otherservicename/resources/12345)