Item-level APIs

Item-Level API Endpoints

The information below provides the basic endpoints currently available at the digital resource (item) level. The main endpoints are demonstrated and then examples of how to use the APIs are also included below.

REST API Item Endpoints

The most commonly used item endpoints are the endpoints that return the citation and the citation with files. These endpoints support json, json-p, xml, and protobuf and represent a SobekCM BriefItem object. In addition, the metadata can be returned as XML in several standard formats. Finally, an endpoint for a random item from an instance and a legacy endpoint are also included for backward compatibility.

Citation Only

This endpoint includes only the citation information about an item and is a serialized instance of the SobekCM BriefItem object, without any images, downloads, or table of content information. Below are some example URLs:

The URL can also include the VID as a five digit number after the BibID. So, the example URL for your instance would be

{BASEURL} / engine / items / citation / {format} / {BibID} / {VID (optionally) }

Brief View ( Citation and Files )

This endpoint is similar to the citation only endpoint above, excep the BriefItem includes the images, downloads, and the table of content information from the structure map in the METS for the digital resource. Below are the same example URLs, including the file information:

Metadata Standards XML API

The metadata associated with the item (and included in the Citation Only endpoint) can also be requested in a variety of standard formats. These responses are written from the digital resource METS file data upon request. Responses from this endpoint are ONLY served as XML, as these are implementations of standard XML schemas.

Random Item

This method gets a random (public) item from a SobekCM instance and returns just the matching BibID and VID. This is used to allow a link to go to random item within an instance. This value is returned only as JSON-P, as it is generally consumed with client-side javascript.

The URL for this endpoint is: {BASEURL} / engine / items / random

For example, http://digital.wolfsonian.org/engine/items/random.

Legacy Item Endpoint

This endpoint is retained for backward compatibility with earlier systems, such as the iPhone application. New development is encouraged to not use this endpoint, but rather the newly added ones above. This endpoint will be deprecated at some future time.

JSON is the only supported interchange format for this endpoint.

The URL for this endpoint is: {BASEURL} / engine / items / legacy / json / {BibID} / {VID (optionally) }

For example, http://ufdc.ufl.edu/engine/items/legacy/json/UF00082548/00001.

Using the Item-Level Endpoints

Internally

Those are what the system will use internally, although they may actually use the PROTO-BUF messages, rather than JSON. The citation then will be another configuration file that dictates the order and grouping of those description elements, and how they appear. That should be soon, so you can customize your description display.

Utilizing via JSON-P within HTML

Below are some very simple examples of using the endpoints to display item pages utilizing only HTML and JQuery. All of the code for these examples appears in the body of the HTML page, and can easily be viewed by viewing the source of the example.

These progressively use different parts of the REST API, and also start to add in very simple external libraries.

Example 1: Citation Only ( http://sobekrepository.org/samples/citation.html )

The example above shows the entire citation, by looping through all elements. The citation is displayed in no particular order, just the order it appears in the JSON response.

Example 2: Improved Citation and Downloadable Files ( http://sobekrepository.org/samples/downloads.html )

In this example, the downloadable files are included as links. In addition, the citation is handled by choosing which fields to display and the order. This citation looks very much like the default citation displayed within the SobekCM web application.

Example 3: Single Image Item ( http://sobekrepository.org/samples/photo.html )

This is a very simple example where the item has a single JPEG image to be displayed. This example is quite common for photograph and postcard items however.

Example 4: Image Item in Gallery ( http://sobekrepository.org/samples/gallery.html )

This example build upon the examples above but displays an item with multiple images. These images are displayed using the jQuery FancyBox library.

Example 5: Book with Page Turning ( http://sobekrepository.org/samples/book.html )

This example displays a book item with a table of contents displayed and utilizing a very simple page turning library.

Consuming Endpoints in Code

You can also consume the main endpoints in code by deserializing the response into an object. If your custom code is written in C# or another .NET language, you can directly utilize the main BriefItem class in the SobekCM.Core class library used throughout the system.

The image below gives a brief anatomy of this object. (select to view larger format)