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.