API Syntax

The OCHRE API provides a mechanism for accessing a published item based on its Citation URL. Any item's Citation URL can be found (and copied) at the bottom of its View pane, or from the Right-click menu option, Copy Citation URL. 

A request of an item's Citation URL, retrieves its published XML document from the OCHRE publication server, delivers it to the client DOM, and transforms it—in full or in part—from XML to HTML.

The base address for the API call is:

https://pi.lib.uchicago.edu/1001/org/ochre/...

To access a published item, add its UUID to the API call. This is the full persistent identifier for a single OCHRE item:

https://pi.lib.uchicago.edu/1001/org/ochre/e5e9d6aa-1e63-461a-a8b3-0ee3ac1b2418

Passing arguments to the API

In accordance with standard URL syntax, arguments are appended to the citation URL with a question mark and multiple arguments are separated with an ampersand.

NOTE: the OCHRE API citation URL encodes the UUID argument as part of the URL, so there is no need to pass an argument like ?uuid=. When the citation URL redirects to the OCHRE item, notice that the UUID has been called using ?uuid=. Because this first argument is encoded in the citation URL with the question mark implied, additional arguments can also be attached simply with an ampersand as shown below. In short, both of the following links are valid:

https://pi.lib.uchicago.edu/1001/org/ochre/baf0d5ae-38fe-452b-aacc-6dc39bee2b06&preview

https://pi.lib.uchicago.edu/1001/org/ochre/baf0d5ae-38fe-452b-aacc-6dc39bee2b06?preview

Parameters for OCHRE Resource items (&preview, &load)

A published OCHRE Resource item can be viewed by calling the API, which will produce a styled HTML page that shows the Resource name, properties, etc. and that loads the Resource in an embedded frame on the page. However, in some instances you will want to deliver the Resource item to the client without this styled framework. For example, you may want to load an image or PDF in the client as an individual file.

To deliver a Resource to the client, use one of two parameters in conjunction with the API call.

To deliver an image preview (e.g., the thumbnail version), add the &preview parameter to the end of the API call.

To load a high-resolution image, PDF, audio file, or video file, add the &load parameter to the end of the API call.

Call the XML document: https://pi.lib.uchicago.edu/1001/org/ochre/baf0d5ae-38fe-452b-aacc-6dc39bee2b06

Call the image preview: https://pi.lib.uchicago.edu/1001/org/ochre/baf0d5ae-38fe-452b-aacc-6dc39bee2b06&preview

Call the high-resolution image: https://pi.lib.uchicago.edu/1001/org/ochre/baf0d5ae-38fe-452b-aacc-6dc39bee2b06&load

To display a PDF: https://pi.lib.uchicago.edu/1001/org/ochre/84a3347e-34f5-4a32-8db4-c15105dcf960&load 

Deliver a ZIP file through the API

For any other file type (Excel spreadsheet, Word document, Photoshop file, etc.), compress the file as a ZIP file and create a resource in OCHRE for the ZIP file. Publish the ZIP resource and use the &load parameter to deliver (download) the ZIP file through the API.

NOTE: these resource parameters deliver content to the DOM without revealing the server address or access credentials in the XML.

To summarize IIIF options:

A <resource> item will present one of the following mutually exclusive options:

EITHER:

1. type = "IIIF"

2. &iiif parameter on API fetch will return JSON with the "manifestUrl" key whose value is the IIIF URL to display in a viewer

OR:

1. type = "IIIF:allmaps"

2. &iiif parameter on API fetch will return raw string content representing a JSON manifest to use as the #data on a call to the Allmaps Viewer

Http Return Codes

The OCHRE API returns appropriate http response codes, as described below. for a variety of scenarios.

If using the Citation URL form of the API (e.g., https://pi.lib.uchicago.edu/1001/org/ochre/.... )

• 200: If the item is found and successfully returned

• 404: If the item is not found; the viewer will see a page indicating that that item has not yet been published

If using the &xquery parameter as described above (e.g., https://ochre.lib.uchicago.edu/ochre?xquery=for $q in input()/ochre[....  )

• 200: If the query succeeds and has a return result 

• 200: If the query succeeds but has no results

• 400 ("Bad request") if the query fails due to bad syntax

If there is an error code (400, 404), or no results, the API will return an empty <result/> (xml) or {"result": []} (json).

If the &format=json option is used, there will be no message provided to the user -- it is assumed that this scenario is under application control.