- URI Syntax:
{prefix}/(eadid|component_id)/tree.(json|xml)
- Parameters:
mode=(arrangement|full|walk|sparse|walkarrangement|sparsearrangement)
E.G.: http://example.edu/prefix/AC044_c0122/tree.xml?mode=sparse
The mode
parameter accepts these values:
arrangement
: (default) Return an outline of theead:dsc
including only subgroup, series and subseries level componentsfull
: Return an outline of the entireead:dsc
walk
: Return only the children of the component or collection with the supplied IDsparse
: Return only the elements of the tree relevant to the component (ancestors and siblings)walkarrangement
: Return only the children of the component with the supplied ID that are of the level typesubgrp
,series
,subseries
sparsearrangement
: Return only the elements of the tree relevant to the component (ancestors and siblings) with the supplied ID that are of the level typesubgrp
,series
,subseries
(You can use this service to test the modes, but note that it doesn't quite follow the URI syntax described above - the ID is a param as well).
Uses EAD XML list syntax, plus two extension attributes, discussed below e.g.:
<list xmlns="urn:isbn:1-931666-22-9" xmlns:xlink="http://www.w3.org/1999/xlink" type="simple">
<item hasChildren="true" containsComponent="false">
<ref xlink:href="http://findingaids.princeton.edu/collections/AC044/c0001" target="AC044_c0001" altrender="series">
<unittitle>Series 1: Committee Administration, 1968-1970</unittitle>
</ref>
</item>
<item hasChildren="true" containsComponent="false">
<ref xlink:href="http://findingaids.princeton.edu/collections/AC044/c0094" target="AC044_c0094" altrender="series">
<unittitle>Series 2: Committees, 1966-1970</unittitle>
</ref>
</item>
<item hasChildren="true" containsComponent="true">
<ref xlink:href="http://findingaids.princeton.edu/collections/AC044/c0111" target="AC044_c0111" altrender="series">
<unittitle>Series 3: Student Organizations, 1968-1970</unittitle>
</ref>
<list type="simple">
<item hasChildren="false" containsComponent="false">
<ref xlink:href="http://findingaids.princeton.edu/collections/AC044/c0112" target="AC044_c0112" altrender="file">
<unittitle>Graduate Student Ballot, 1968</unittitle>
</ref>
</item>
<item hasChildren="false" containsComponent="false">
<ref xlink:href="http://findingaids.princeton.edu/collections/AC044/c0113" target="AC044_c0113" altrender="file">
<unittitle>Graduate Student Organization: Departmental Surveys, 1969</unittitle>
</ref>
</item>
...
For every mode except arrangement
, two additional attributes should be added to the ead:item
element.
hasChildren="(true|false)"
indicates whether or not a component has children (since these may not be shown in the view of the tree requested)containsComponent="(true|false)"
istrue
if the item contains the component that was indicated in theid
parameter. This is useful when, e.g., usingsparsearrangement
mode and sending theid
for a component that is at a lower level (i.e.box
,file
,item
) than is going to be included in the response.
TODO
Yes, use them appropriately. 200, 204, 400, 404 are the most common cases. 204 (No Content) warrants some explanation: it should be used when mode
is walk
or walkarrangement
and there are no children, e.g.:
curl -Gv -H "Accept:application/xml" "http://fincingaids.princeton.edu/_services/tree?id=AC264_c00003&mode=walk"
< HTTP/1.1 204 No Content
< Date: Wed, 30 Nov 2011 22:41:26 GMT
< Server: Jetty/5.1.12 (Linux/3.0.0-13-generic amd64 java/1.6.0_23
< Pragma: no-cache
< Cache-Control: no-cache
< Content-Length: 0
< Content-Type: text/plain