Using the OCHRE API
By Miller Prosser, May 2020
Updated by S. Schloen, Feb 2024
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
Viewing API Output
By default, the OCHRE API will style the fetched data using its default stylesheet (an xslt) to create an HTML view. However, a developer will want to inspect and process the XML output. There are various strategies for calling and viewing an XML document delivered from the OCHRE API.
OPTION #1 (&xsl)
Load the XML document in a web browser and suppress the style sheet.
https://pi.lib.uchicago.edu/1001/org/ochre/a4283f3c-f942-4669-a7f3-ab01d580d875&xsl=none
Notice the &xsl=none at the end of the API call. This will suppress the XML transformation. Note, however, that many browsers attempt to transform the XML document into HTML. When the XML document loads, the page may look like unformatted, running text. Use your browser to Inspect the page or View page source. Browsers use different terminology for these actions as well. Alternatively, provide a valid path to an alternate stylesheet using the &xsl=path-to-style-sheet option.
OPTION #2
Open the XML document in Oxygen XML Editor or another XML editing program. In Oxygen, you can use File > Open URL... to open the API call. There is no need to suppress the style sheet in this scenario. You can simply open the persistent identifier.
OPTION #3
Use curl and xmllint to open the document in a Terminal.
curl -L "https://pi.lib.uchicago.edu/1001/org/ochre/e59a5d19-0ea8-49c4-a814-05c6674f0f0a" | xmllint --format - | less
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.
Creating your own request for data (&xquery)
While the Citation URL performs, in effect, an XQuery against the publication database using an item's UUID as a key for lookup. However, you can perform very powerful XQueries of your own by using the &xquery parameter.
{ Examples to follow ... }
Multi-lingual content (&lang)
The xml:lang attribute identifies the language of the <content>. The languages attribute indicates which languages are effectively supported by the contained <string>s. Here, for example, the Script type <value> has not been given an English equivalent, and so languages indicates that the provided <string> supports both Turkish and English ("tur;eng").
Projects can opt into entering content in multiple languages in OCHRE. When published, multi-lingual <content> is present in the xml, identified by the 3-character country code in the xml:lang attribute.
By default, the OCHRE API will return content in the project's default language.
The &lang parameter filters the content based on the requested language, falling back to the default (or available) language, if the requested language is not represented.
Use &lang="*" for all content, with no language filtering. The app developer is then free to target the needed content (e.g., using the "xml:lang" attribute).
The "languages" attribute on the root <ochre> node identifies the languages in which the project has chosen to publish. If there is no "languages" attribute at all, this indicates that the project has not adopted the multi-lingual features of OCHRE and there will be no language filtering provided.
The default language of the project is found on the Dublin Core <metadata><language> element :
<ochre><metadata><language xmlns:dc="http://purl.org/dc/elements/1.1/">eng</language>Use &lang="zxx" to request only Aliases (akas). Otherwise, all Aliases will be included by default regardless of what language is specified.
The <document> node (of an OCHRE "internal document" Resource) is a special case, often including ancient, legacy, or other scholarly languages, that returns all content, ignoring the &lang parameter. App developers are encouraged to explore this content and target specific languages, as needed
Data returned by using the &xquery parameter bypasses any language filtering unless specifically requested (e.g., it does not automatically filter to the default language). The expectation is that one could use the xquery to target selected content as needed.
Supported formats (&format)
By default, data is returned from the OCHRE API as XML.
To request JSON instead, simply add &format=json as a parameter.
Special outputs
&iiif
For an OCHRE Resource item of Type = "IIIF", the manifest can be fetched using the &iiif parameter. This is always returned as JSON by default, and the value of the "manifest" key can be extracted for processing by a IIIF Viewer.
https://ochre.lib.uchicago.edu/ochre?uuid=5902ea1d-5665-4a29-875b-b096245a2f81&iiif
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.
Troubleshooting
Ad Blockers — certain ad blockers and other privacy extensions to web browsers may cause content from the API to be blocked even when the OCHRE URL is added to the list of approved sites. This problem usually presents as what seems to be broken image links. Sometimes an ad blocker will prevent XML data from being delivered to the browser, resulting in what looks like a frozen site. Test your browser settings by toggling off each extension one at a time and refreshing the page. This will help isolate the offending extension.
CORS — Cross-origin Resource Sharing (CORS) allows a website to load information from another domain. If you notice a CORS-related error in your developer console, this may be due to a browser setting that restricts what content can be loaded using a local host. Most browsers have a setting that allows for CORS while using a local host for development. There are various solutions to this problem. Further, many browsers require all content on a website to be delivered using the same level of security. If the site uses https://, then any links on that page must be delivered using https://. A protocol mismatch may result in a mixed-content error.
GitHub user.name — Should GitHub fail to initialize you as the owner of a local repository, you may need to enter your name and email. VS Code or GitHub may pop up a message like "Make sure you configure your 'user.name' and 'user.email' in git."
To use a JavaScript method like fetch(), the API call must be configured to follow a redirect. See the Web API documentation on MDN.