Skip to content

ExplanationOfDifferentResponses

Jump to bottom
Tyler Danstrom edited this page Aug 15, 2017 · 1 revision

The different types of responses

The consuming client must be able to distinguish between the kinds of responses that the ldr metadata storage will provide. If the response is aggregate, it means the consuming client needs to know what collections are present in a particular location in the ldr metadata storage. If the response is atomic, it means the consuming client needs to know something in particular about a particular collection or proxy metadata. If the response is contextual, it means the consuming client needs to know where it can go next on its journey through the ldr metadata storage. In this way, the consuming client can navigate its way through the ldr metadata storage and be able to quickly interpret the responses based on a check for responseType to verify that the responseType is the kind of response it wants.

Regardless of type, every response will have certain characteristics in common. Each one will have

  • it will have the following namespaces
    • http://lib.uchicago.edu/ldr which this document refers to with the shorthand ldr
    • http://www.w3.org/2001/XMLSchema-instance which this document refers to with the shorthand xsi
    • http://purl.org/dc/elements/1.1/ which this document refers to with the shorthand dc
    • http://purl.org/dc/terms/ which this document refers to with the shorthand dcterms
  • a request field which will have a value of the request being asked of the system.
  • a requestReceivedTimeStamp which will have a value of the date and time that the system received the request in ISO-8601
  • a requestSentTimeStamp which will have a value of the date and time that the system completed processing the request in ISO-8601 and sent it to the consuming client
  • a responseType which will have as a value a string that is either aggregate, atomic, or contextual
  • a response body which will contain the metadata that is the answer to the request

About aggregate type responses

An aggregate response is one that that the consuming client can assume will present a list of collections that match the request

The following endpoints are aggregate

  • /collections
  • /collections/[collection identifier][/sub-collection identifier]?
  • /collection/[collection identifier]/proxies

The aggregate response body metadata will consist of at least one dc:hasPart with attribute xsi:type="dcterms:URI". The value of each dc:hasPart will be a URI for a collection (if any) that are direct subordinate to the collection being requested about or a URL for an asset that is directly subordinate to the collection.

Contract for aggregate responses

<?xml version="1.0" encoding="utf-8"?>
<output xmlns="http://lib.uchicago.edu/ldr"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:dc="http://purl.org/dc/elements/1.1/"
        xmlns:dcterms="http://purl.org/dc/terms/">
    <request>/collections/mvol</request>
    <requestReceivedTimeStamp>2017-07-28T14:02:12-06:00</requestReceivedTimeStamp>
    <responseSentTimeStamp>2017-07-28T14:02:17+07:00</responseSentTimeStamp>
    <responseType>aggregate</responseType>
    <response>
        <metadata>
            <dc:hasPart xsi:type="dcterms:URI">/collection/mvol/0001</dc:hasPart>
            <dc:hasPart xsi:type="dcterms:URI">/collection/mvol/0002</dc:hasPart>
            <dc:hasPart xsi:type="dcterms:URI">/collection/mvol/0004</dc:hasPart>
            <dc:hasPart xsi:type="dcterms:URI">/collection/mvol/0446</dc:hasPart>
        </metadata>
    </response>
</output>
<?xml version="1.0" encoding="utf-8"?>
<output xmlns="http://lib.uchicago.edu/ldr"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:dc="http://purl.org/dc/elements/1.1/"
        xmlns:dcterms="http://purl.org/dc/terms/">
    <request>/collections/mvol/0001</request>
    <requestReceivedTimeStamp>2017-07-28T14:02:12-06:00</requestReceivedTimeStamp>
    <responseSentTimeStamp>2017-07-28T14:02:17+07:00</responseSentTimeStamp>
    <responseType>aggregate</responseType>
    <response>
        <metadata>
            <dc:hasPart xsi:type="dcterms:URI">/collection/mvol/0001/0000</dc:hasPart>
            <dc:hasPart xsi:type="dcterms:URI">/collection/mvol/0001/0001</dc:hasPart>
            <dc:hasPart xsi:type="dcterms:URI">/collection/mvol/0001/0002</dc:hasPart>
            <dc:hasPart xsi:type="dcterms:URI">/collection/mvol/0001/0003</dc:hasPart>
        </metadata>
    </response>
</output>
<?xml version="1.0" encoding="utf-8"?>
<output xmlns="http://lib.uchicago.edu/ldr"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:dc="http://purl.org/dc/elements/1.1/"
        xmlns:dcterms="http://purl.org/dc/terms/">
    <request>/collections/mvol/0001/0003</request>
    <requestReceivedTimeStamp>2017-07-28T14:02:12-06:00</requestReceivedTimeStamp>
    <responseSentTimeStamp>2017-07-28T14:02:17+07:00</responseSentTimeStamp>
    <responseType>aggregate</responseType>
    <response>
        <metadata>
            <dc:hasPart xsi:type="dcterms:URI">/collection/mvol/0001/0003/0000</dc:hasPart>
            <dc:hasPart xsi:type="dcterms:URI">/collection/mvol/0001/0003/0001</dc:hasPart>
            <dc:hasPart xsi:type="dcterms:URI">/collection/mvol/0001/0003/0002</dc:hasPart>
            <dc:hasPart xsi:type="dcterms:URI">/collection/mvol/0001/0003/0003</dc:hasPart>
        </metadata>
    </response>
</output>
<?xml version="1.0" encoding="utf-8"?>
<output xmlns="http://lib.uchicago.edu/ldr"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:dc="http://purl.org/dc/elements/1.1/"
        xmlns:dcterms="http://purl.org/dc/terms/">
    <request>/collections/mvol/0001/0003/0001</request>
    <requestReceivedTimeStamp>2017-07-28T14:02:12-06:00</requestReceivedTimeStamp>
    <responseSentTimeStamp>2017-07-28T14:02:17+07:00</responseSentTimeStamp>
    <responseType>aggregate</responseType>
    <response>
        <metadata>
            <dc:hasPart xsi:type="dcterms:URL">http://digcollretriever.lib.uchicago.edu/mvol-0001-0003-0001/pdf</dc:hasPart>
            <dc:hasPart xsi:type="dcterms:URL">http://digcollretriever.lib.uchicago.edu/mvol-0001-0003-0001/jejocr</dc:hasPart>
            <dc:hasPart xsi:type="dcterms:URL">http://digcollretriever.lib.uchicago.edu/mvol-0001-0003-0001_0001/jpg</dc:hasPart>
            <dc:hasPart xsi:type="dcterms:URL">http://digcollretriever.lib.uchicago.edu/mvol-0001-0003-0001_0002/jpg</dc:hasPart>
            <dc:hasPart xsi:type="dcterms:URL">http://digcollretriever.lib.uchicago.edu/mvol-0001-0003-0001_0003/jpg</dc:hasPart>
            <dc:hasPart xsi:type="dcterms:URL">http://digcollretriever.lib.uchicago.edu/mvol-0001-0003-0001_0004/jpg</dc:hasPart>
        </metadata>
    </response>
</output>
<?xml version="1.0" encoding="utf-8"?>
<output xmlns="http://lib.uchicago.edu/ldr"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:dc="http://purl.org/dc/elements/1.1/"
        xmlns:dcterms="http://purl.org/dc/terms/">
    <request>/collections/mvol/0001/0003/0001/proxies</request>
    <requestReceivedTimeStamp>2017-07-28T14:02:12-06:00</requestReceivedTimeStamp>
    <responseSentTimeStamp>2017-07-28T14:02:17+07:00</responseSentTimeStamp>
    <responseType>aggregate</responseType>
    <response>
        <metadata>
            <dc:relation xsi:type="dcterms:URI">/collection/mvol-0001-0003-0001/proxies/structMetadata</dc:hasPart>
        </metadata>
    </response>
</output>

About atomic responses

An atomic response is one that the consuming client can assume will be present a single descriptive metadata

The following endpoints are atomic:

  • /collection/[collection identifier]/core
  • /collection/[collection identifier]/proxies/[proxy identifier]

The atomic response body metadata will consist of the following

  • one dc:identifier element the value of which is the primary access point for the collection
  • one dc:title element the value of which is the primary intellectual secondary access point for the collection

In addition, the atomic response body may have the following

  • at least one dc:hasPart which will point to either a collection or an asset which is a direct subordinate of the collection
  • at least one dc:isPartOf which will point to a collection of which the collection is directly subordinate
  • one dc:date which is a secondary intellectual access point
  • one dc:creator which is a secondary intellectual access point
  • one dc:description which which relays contextual semantic information about the collection to the biological being on whose behalf the consuming client is working

Contract for atomic responses

<?xml version="1.0" encoding="utf-8"?>
<output xmlns="http://lib.uchicago.edu/ldr"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:dc="http://purl.org/dc/elements/1.1/"
        xmlns:dcterms="http://purl.org/dc/terms/">
    <request>/collection/mvol-0001/core</request>
    <requestReceivedTimeStamp>2017-07T12:02:44-06:00</requestReceivedTimeStamp>
    <responseSentTimeStamp>2017-07-28T12:02:58+03:00</responseSentTimeStamp>
    <responseType>atomic</responseType>
    <response>
        <metadata>
            <dc:title>Cap and Gown</dc:title>
            <dc:identifier>mvol-0001</dc:identifier>
            <dc:isPartOf xsi:type="dcterms:URI">/collections/mvol</dc:isPartOf>
        <metadata>
    </response>
</output>
<?xml version="1.0" encoding="utf-8"?>
<output xmlns="http://lib.uchicago.edu/ldr"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:dc="http://purl.org/dc/elements/1.1/"
        xmlns:dcterms="http://purl.org/dc/terms/">
    <request>/collection/mvol-0001-0002/core</request>
    <requestReceivedTimeStamp>2017-07T12:02:44-06:00</requestReceivedTimeStamp>
    <responseSentTimeStamp>2017-07-28T12:02:58+03:00</responseSentTimeStamp>
    <responseType>atomic</responseType>
    <response>
         <metadata>
            <dc:title>Cap and Gown Volume 2</dc:title>
            <dc:identifier>mvol-0001-0002</dc:identifier>
            <dc:isPartOf xsi:type="dcterms:URI">/collections/mvol/0001</dc:iisPartOf>
        <metadata>
    </response>
</output>
<?xml version="1.0" encoding="utf-8"?>
<output xmlns="http://lib.uchicago.edu/ldr"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:dc="http://purl.org/dc/elements/1.1/"
        xmlns:dcterms="http://purl.org/dc/terms/">
    <request>/units/mvol-0001-0002-0004/core</request>
    <requestReceivedTimeStamp>2017-07T12:02:44-06:00</requestReceivedTimeStamp>
    <responseSentTimeStamp>2017-07-28T12:02:58+03:00</responseSentTimeStamp>
    <responseType>atomic</responseType>
    <response>
            <metadata>
                <dc:title>Cap and Gown volume 2, issue 4</dc:title>
                <dc:date>1900-02-01</dc:date>
                <dc:creator>University of Chicago</dc:creator>
                <dc:title>Cap and Gown Volume 2, Issue 4</dc:title>
                <dc:identifier>mvol-0001-0002-0004</dc:identifier>
                <dc:isPartOf xsi:type="dcterms:URI">/collections/mvol/0001/0002</dc:identifier>
                <dci:hasPart xsi:type=="dcterms:URL">http://digcollretriever.lib.uchicago.edu/mvol-0001-002-0004/pdf</dc:hasPart>
                <dc:hasPart xsi:type=="dcterms:URL">http://digcollretriever.lib.uchicago.edu/mvol-0001-002-0004/metadata</dc:hasPart>
                <dc:hasPart xsi:type=="dcterms:URL">http://digcollretriever.lib.uchicago.edu/mvol-0001-002-0004/jejocr</dc:hasPart>
                <dc:hasPart xsi:type=="dcterms:URL">http://digcollretriever.lib.uchicago.edu/mvol-0001-002-0004_0001</dc:hasPart>
                <dc:hasPart xsi:type=="dcterms:URL">http://digcollretriever.lib.uchicago.edu/mvol-0001-002-0004_0002</dc:hasPart>
                <dc:hasPart xsi:type=="dcterms:URL">http://digcollretriever.lib.uchicago.edu/mvol-0001-002-0004_0003</dc:hasPart>
                <dc:hasPart xsi:type=="dcterms:URL">http://digcollretriever.lib.uchicago.edu/mvol-0001-002-0004_0004</dc:hasPart>
            <metadata>
    </response>
</output>
<?xml version="1.0" encoding="utf-8"?>
<output xmlns="http://lib.uchicago.edu/ldr"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:dc="http://purl.org/dc/elements/1.1/"
        xmlns:dcterms="http://purl.org/dc/terms/">
    <request>/collection/mvol-0001-0002-0004/proxies/structuralMetadata</request>
    <requestReceivedTimeStamp>2017-07T12:02:44-06:00</requestReceivedTimeStamp>
    <responseSentTimeStamp>2017-07-28T12:02:58+03:00</responseSentTimeStamp>
    <responseType>atomic</responseType>
    <response>
        <proxy>
            <dc:description>this is structural metadata information about mvol-0001-002-0004M</dc:description>
            <data>
                <!-- insert base64 of struct.txt file for mvol-0001-0002-0004 -->
            </data>
        </proxy>
    </response>
</output>

About contextual responses

A contextual response is one that merely tells the client which endpoints can be discovered from the particular endpoint that the client is at. It is a form of wayfinding, as if the consuming client is on a forest trail and has reached a fork in the road.

The following endpoints are contextual

  • /
  • /collection/[collection identifier]

The contextual response body metadata will consist of the following

  • at least one dc:relation element the value of which is an endpoint available to the endpoint being requested

Contract for contextual responses

<?xml version="1.0" encoding="utf-8"?>
<output xmlns="http://lib.uchicago.edu/ldr"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:dc="http://purl.org/dc/elements/1.1/"
        xmlns:dcterms="http://purl.org/dc/terms/">
    <request>/</request>
    <requestReceivedTimeStamp>2017-07T12:02:44-06:00</requestReceivedTimeStamp>
    <responseSentTimeStamp>2017-07-28T12:02:58+03:00</responseSentTimeStamp>
    <responseType>contextual</responseType>
    <response>
        <data>
            <metadata>
                <dc:relation xsi:type="dcterms:URI">/collections</dc:relation>
            <metadata>
        </data>
    </response>
</output>
<?xml version="1.0" encoding="utf-8"?>
<output xmlns="http://lib.uchicago.edu/ldr"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:dc="http://purl.org/dc/elements/1.1/"
        xmlns:dcterms="http://purl.org/dc/terms/">
    <request>/collection/mvol-0001-0002/core</request>
    <requestReceivedTimeStamp>2017-07T12:02:44-06:00</requestReceivedTimeStamp>
    <responseSentTimeStamp>2017-07-28T12:02:58+03:00</responseSentTimeStamp>
    <responseType>contextual</responseType>
    <response>
        <data>
            <metadata>
                <dc:relation xsi:type="dcterms:URI">/collections/mvol-0001-0002/core</dc:relation>
                <dc:relation xsi:type="dcterms:URI">/collections/mvol-0001-0002/proxies</dc:relation>
            <metadata>
        </data>
    </response>
</output>
Clone this wiki locally