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