Archives/EAD Tree Navigation API spec

tree_spec.md

API For Archival Collection Tree Browsing

• 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

Mode Definitions

The mode parameter accepts these values:

1. arrangement: (default) Return an outline of the ead:dsc including only subgroup, series and subseries level components
2. full: Return an outline of the entire ead:dsc
3. walk : Return only the children of the component or collection with the supplied ID
4. sparse: Return only the elements of the tree relevant to the component (ancestors and siblings)
5. walkarrangement : Return only the children of the component with the supplied ID that are of the level type subgrp, series, subseries
6. sparsearrangement : Return only the elements of the tree relevant to the component (ancestors and siblings) with the supplied ID that are of the level type subgrp, 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).

XML Syntax

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)" is true if the item contains the component that was indicated in the id parameter. This is useful when, e.g., using sparsearrangement mode and sending the id for a component that is at a lower level (i.e. box, file, item) than is going to be included in the response.

JSON Syntax

TODO

HTTP Responses

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