Digital Collections HTTP API Documentation

Character encoding

The API returns all character data as UTF-8, and expects to receive it as UTF-8 as well.

Status codes

Clients should depend on the numeric HTTP status code only, not the result message. In addition to the documented status codes below, clients should be prepared to handle unexpected 500-level errors in response to any request.

Content representations

This API service will output XML, JSON, or JSONP depending on the order of preference expressed by your HTTP client in the Accept header. This can be overridden by appending one of the extensions below to the URI.

URI extension MIME type Notes
XML .xml application/xml XML records are in the http://digital.library.unlv.edu namespace. They use XLink for cross-document hyperlinking and XML Schema for validation.
JSON .json application/json
JSONP .jsonp text/javascript JSONP wraps JSON output inside a JavaScript callback function. By default, this function is named dmBridgeRequest, but a custom function name can be specified with the callback query string parameter; e.g. ?callback=myFunction.

Other notes

Please be respectful of this server's limited processing and bandwidth resources, and employ caching where possible and appropriate.

API methods

Objects
List all objects in a collection api/1/objects/[alias]
List the highest rated objects in a collection api/1/objects/[alias]/highest_rated
View a specific object api/1/objects/[alias]/[pointer]
Search for objects based on their metadata api/1/search
Search for objects by rating api/1/search_by_rating
Retrieve an object's bitstream api/1/objects/[alias]/[pointer]/bitstream
Retrieve an excerpt of an object's bitstream api/1/objects/[alias]/[pointer]/excerpt
Search within the full text of an object api/1/objects/[alias]/[pointer]/search
View an object's rating api/1/objects/[alias]/[pointer]/rating
Rate an object api/1/objects/[alias]/[pointer]/rating
View an object's thumbnail image api/1/objects/[alias]/[pointer]/thumbnail
View a random object api/1/objects/random
Retrieve an object's spatial bounds api/1/objects/[alias]/[ptr]/bounds
Search for objects based on their spatial area api/1/spatial_search
View the highlighted object api/1/objects/highlighted
Collections
List all collections api/1/collections
View a specific collection api/1/collections/[alias]
Comments
Search for comments api/1/comments
List all comments on an object api/1/objects/[alias]/[pointer]/comments
Post a new comment api/1/objects/[alias]/[pointer]/comments
View a specific comment api/1/comments/[id]
Tags
Search for tags api/1/tags
List all tags for an object api/1/objects/[alias]/[pointer]/tags
Post a new tag api/1/objects/[alias]/[pointer]/tags
View a specific tag api/1/tags/[id]
Vocabulary
View vocabulary term frequencies within one or multiple fields of a collection api/1/vocabulary/[alias]/[field]
Suggest vocabulary terms that match a given string (search suggestions) api/1/vocabulary/suggest
API Information
Retrieve API status information api/1/status

List all objects in a collection

Retrieves all objects in a collection in a paginated list. The default number of results per page is 20.

HTTP method

GET api/1/objects/[alias]

Query parameters

Key Required? Description Allowed Values Default Value
page No Page number
  • Positive integer
 1
rpp No Results per page
  • Integer between 10 and 100
 50
sort No Nickname of the field by which to sort
order No Sort order
  • asc: Ascending
  • desc: Descending
 asc

Status codes

200 OK
The request succeeded.
404 Not Found
The collection with specified [alias] either does not exist or is unpublished.

Examples

List the highest rated objects in a collection

HTTP method

GET api/1/objects/[alias]/highest_rated

Query parameters

Key Required? Description Allowed Values Default Value
rpp No Results per page
  • Integer between 10 and 100
 50

Status codes

200 OK
The request succeeded.
501 Not Implemented
Ratings are not available from this service.

Examples

View a specific object

View an object identified by collection alias [alias] and pointer [pointer].

HTTP method

GET api/1/objects/[alias]/[pointer]

Query parameters

None

Status codes

200 OK
The request succeeded.
404 Not Found
The object with specified [alias] and [pointer] either does not exist or is in an unpublished collection.

Examples

Search for objects based on their metadata

Up to four search terms can be used in a query. Each term is composed of a string (text to search for), a matching mode, and a metadata field in which to search.

HTTP method

GET api/1/search

Query parameters

Key Required? Description Allowed Values Default Value
q No Simple string query; an alternative to the "CISO" parameters below. If this is supplied, the "CISO" parameters are not necessary.
CISOOP[1-4] Yes Matching mode
  • all: Match objects that contain all words in the search string
  • exact: Match objects that contain the exact search string
  • any: Match objects that contain any of the words in the search string
  • none: Match objects that do not contain any of the words in the search string
CISOBOX[1-4] Yes Search string
CISOFIELD[1-4] Yes Nickname of the field in which to search
  • A valid field nickname
  • CISOSEARCHALL: Search across all fields
CISOROOT Yes A valid collection alias; multiple aliases separated by commas; or the word "all" to search across all collections
page No Page number
  • Positive integer
 1
rpp No Results per page
  • Positive integer between 10 and 100
 50
sort No Nickname of the field by which to sort
order No Sort order
  • asc: Ascending
  • desc: Descending
 asc

Status codes

200 OK
The request succeeded.
400 Bad Request
Parameters were supplied in an unexpected format.

Examples

Search for objects by rating

Searches for objects based on the specified rating thresholds.

HTTP method

GET api/1/search_by_rating

Query parameters

Key Required? Description Allowed Values Default Value
page No Page number
  • Positive integer
 1
rpp No Results per page
  • Positive integer between 10 and 100
 50
min_rating Yes Minimum rating threshold
  • Positive decimal between 0 and 1.
max_rating Yes Maximum rating threshold
  • Positive decimal between 0 and 1.
collections No Collections
  • A valid collection alias, or multiple aliases separated by commas, to which to limit the search.

Status codes

200 OK
The request succeeded.
400 Bad Request
Parameters were supplied in an unexpected format.
501 Not Implemented
Ratings are not available from this service.

Examples

Retrieve an object's bitstream

Retrieves an object's bitstream (file).

HTTP method

GET api/1/objects/[alias]/[pointer]/bitstream

Query parameters

None

Status codes

200 OK
The request succeeded.
404 Not Found
The object with specified [alias] and [pointer] either does not exist or is in an unpublished collection.

Examples

Retrieve an excerpt of an object's bitstream

Retrieves an excerpt of an object's bitstream (file). Currently only works with PDF objects.

HTTP method

GET api/1/objects/[alias]/[pointer]/excerpt

Query parameters

Key Required? Description Allowed Values Default Value
page Yes Page number, for PDF objects only
format No Output file format, for PDF objects only.
  • pdf

Status codes

200 OK
The request succeeded.
400 Bad Request
Parameters were supplied in an unexpected format.
404 Not Found
The object with specified [alias] and [pointer] either does not exist or is in an unpublished collection; or there is no excerpt available for it.

Examples

Search within the full text of an object

HTTP method

GET api/1/objects/[alias]/[pointer]/search

Query parameters

Key Required? Description Allowed Values Default Value
term Yes Search string

Status codes

200 OK
The request succeeded.
400 Bad Request
Parameters were supplied in an unexpected format.

Examples

View an object's rating

Returns an object's mean rating along with the number of times it has been rated. Note that this information is also available in the object's representation (objects/[alias]).

HTTP method

GET api/1/objects/[alias]/[pointer]/rating

Query parameters

None

Status codes

200 OK
The request succeeded.
404 Not Found
The object with specified [alias] and [pointer] either does not exist or is in an unpublished collection.
501 Not Implemented
Ratings are not available from this service.

Examples

Rate an object

Rates an object on a numeric scale. Note: The client should check (using the status method) whether the server supports object ratings before soliciting them from the user.

HTTP method

POST api/1/objects/[alias]/[pointer]/rating

Query parameters

Key Required? Description Allowed Values Default Value
value Yes Rating value
  • 0-100

Status codes

204 No Content
The request succeeded.
400 Bad Request
Invalid parameters were supplied.
403 Forbidden
New ratings are not currently being accepted.
404 Not Found
The object with specified [alias] and [pointer] either does not exist or is in an unpublished collection.

View an object's thumbnail image

Returns an object's thumbnail image.

HTTP method

GET api/1/objects/[alias]/[pointer]/thumbnail

Query parameters

None

Status codes

200 OK
The request succeeded.
404 Not Found
The object with specified [alias] and [pointer] either does not exist or is in an unpublished collection.

Examples

View a random object

HTTP method

GET api/1/objects/random

Query parameters

None

Status codes

200 OK
The request succeeded.
204 No Content
There are currently no objects in the random object pool on the server.

Examples

Retrieve an object's spatial bounds

HTTP method

GET api/1/objects/[alias]/[ptr]/bounds

Query parameters

None

Status codes

200 OK
The request succeeded.
404 Not Found
The object with specified [alias] and [pointer] either does not exist or is in an unpublished collection.

Examples

Search for objects based on their spatial area

HTTP method

GET api/1/spatial_search

Query parameters

Key Required? Description Allowed Values Default Value
CISOROOT Yes Aliases of collections in which to search
lat_n Yes North latitude, in decimal degrees
lat_s Yes South latitude, in decimal degrees
long_e Yes East longitude, in decimal degrees
long_w Yes West longitude, in decimal degrees
mode No Matching mode, in decimal degrees
  • within: Retrieve objects completely within the specified latitude/longitude coordinates
  • intersect: Retrieve objects completely or partially intersecting the specified latitude/longitude coordinates
  • outside: Retrieve objects completely outside the specified latitude/longitude coordinates
 within
page No Page number 1
rpp No Results per page 50
sort No Nickname of the field by which to sort
order No Sort order
  • asc: Ascending
  • desc: Descending
 asc

Status codes

200 OK
The request succeeded.
400 Bad Request
Parameters were supplied in an unexpected format.

Examples

View the highlighted object

HTTP method

GET api/1/objects/highlighted

Query parameters

None

Status codes

200 OK
The request succeeded.
204 No Content
There is currently no highlighted object on the server.

Examples

List all collections

Lists all public collections. Note that this does not list any objects within the collections. To list objects within a single collection, use objects/[alias]. There is currently no way to list all objects within all collections.

HTTP method

GET api/1/collections

Query parameters

None

Status codes

200 OK
The request succeeded.

Examples

View a specific collection

Returns the collection with alias [alias]. Note that this does not list any objects within the collection; for that, use objects/[alias].

HTTP method

GET api/1/collections/[alias]

Query parameters

None

Status codes

200 OK
The request succeeded.
404 Not Found
The collection with specified [alias] either does not exist or is unpublished.

Examples

Search for comments

Returns a paginated list of all approved comments in the system matching the given criteria, sorted in descending order by posting date.

HTTP method

GET api/1/comments

Query parameters

Key Required? Description Allowed Values Default Value
page No Page number
  • Positive integer
 1
rpp No Results per page
  • Positive integer between 10 and 100
 50
term No Search term
  • A term to search for within the comment body. Only comments containing this term will be retrieved.
collections No Collections
  • A valid collection alias, or multiple aliases separated by commas, to which to limit the search.
objects No Objects
  • A comma-separated list of object alias/pointer pairs, which themselves are separated by slashes; e.g "alias1/ptr1,alias2/ptr2". Only comments on these objects will be retrieved.

Status codes

200 OK
The request succeeded.
501 Not Implemented
Comments are not available from this service.

Examples

List all comments on an object

Lists all approved comments for an object.

HTTP method

GET api/1/objects/[alias]/[pointer]/comments

Query parameters

Key Required? Description Allowed Values Default Value
page No Page number
  • Positive integer
 1
rpp No Results per page
  • Integer between 10 and 100
 50

Status codes

200 OK
The request succeeded.
404 Not Found
The object with specified [alias] and [pointer] either does not exist or is in an unpublished collection.
501 Not Implemented
Comments are not available from this service.

Examples

Post a new comment

Posts a new comment. Note: The client should check (using the status method) whether commenting is available before soliciting comments from the user.

HTTP method

POST api/1/objects/[alias]/[pointer]/comments

Query parameters

Key Required? Description Allowed Values Default Value
text Yes Comment body
name Yes Name or nickname of the person posting the comment
email No Email address of the person posting the comment
  • Valid e-mail address

Status codes

201 Created
The request succeeded and the comment has been posted. The URI of the comment is returned in the Location header.
202 Accepted
The request succeeded and the comment may or may not eventually be posted.
400 Bad Request
Invalid parameters were supplied.
403 Forbidden
New comments are not currently being accepted.
404 Not Found
The object with specified [alias] and [pointer] either does not exist or is in an unpublished collection.

View a specific comment

Returns the comment with id [id]. Only approved comments are available.

HTTP method

GET api/1/comments/[id]

Query parameters

None

Status codes

200 OK
The request succeeded.
404 Not Found
The comment with id [id] either does not exist or has not been approved.
501 Not Implemented
Comments are not available from this service.

Examples

Search for tags

Returns a paginated list of all tags in the system matching the given criteria, grouped by frequency.

HTTP method

GET api/1/tags

Query parameters

Key Required? Description Allowed Values Default Value
page No Page number
  • Positive integer
 1
rpp No Results per page
  • Positive integer between 10 and 100
 50
sort No Results sorting method
  • (null): Sort descending by frequency
  • random: Randomize the results
 null
term No Search term
  • A term to search for within the tag. Only tag containing this term will be retrieved.
collections No Collections
  • A valid collection alias, or multiple aliases separated by commas, to which to limit the search.
objects No Objects
  • A comma-separated list of object alias/pointer pairs, which themselves are separated by slashes; e.g "alias1/ptr1,alias2/ptr2". Only tags on these objects will be retrieved.

Status codes

200 OK
The request succeeded.
501 Not Implemented
Tags are not available from this service.

Examples

List all tags for an object

Lists all approved tags for an object.

HTTP method

GET api/1/objects/[alias]/[pointer]/tags

Query parameters

None

Status codes

200 OK
The request succeeded.
404 Not Found
The object with specified [alias] and [pointer] either does not exist or is in an unpublished collection.
501 Not Implemented
Tags are not available from this service.

Examples

Post a new tag

Posts a new tag. Note: The client should check (using the status method) whether tagging is available before soliciting tags from the user.

HTTP method

POST api/1/objects/[alias]/[pointer]/tags

Query parameters

Key Required? Description Allowed Values Default Value
value Yes Tag text
  • String between 2 and 50 characters long

Status codes

201 Created
The request succeeded and the tag has been posted. The URI of the tag is returned in the Location header.
202 Accepted
The request succeeded and the tag may or may not eventually be posted.
400 Bad Request
Invalid parameters were supplied.
403 Forbidden
New tags are not currently being accepted.
404 Not Found
The object with specified [alias] and [pointer] either does not exist or is in an unpublished collection.

View a specific tag

Returns the tag with id [id]. Only approved tags are available.

HTTP method

GET api/1/tags/[id]

Query parameters

None

Status codes

200 OK
The request succeeded.
404 Not Found
The tag with id [id] either does not exist or has not been approved.
501 Not Implemented
Tags are not available from this service.

Examples

View vocabulary term frequencies within one or multiple fields of a collection

Returns counts of vocabulary terms contained within field [field] of collection with alias [alias].

HTTP method

GET api/1/vocabulary/[alias]/[field]
GET api/1/vocabulary/[alias]/[field1,field2]

Query parameters

None

Status codes

200 OK
The request succeeded.
404 Not Found
Either [field] is not available within collection [alias]; or the collection with specified [alias] does not exist or is unpublished.

Examples

Suggest vocabulary terms that match a given string (search suggestions)

Returns the vocabulary contained within field [field] of collection with alias [alias].

HTTP method

GET api/1/vocabulary/suggest

Query parameters

Key Required? Description Allowed Values Default Value
CISOFIELD[1..*] Yes Nick of the field in which to search; use multiple occurrences of this key (with unique numeric suffixes) to search multiple fields
CISOROOT Yes Alias of a specific collection in which to search
CISOBOX1 Yes String for which suggestions should be provided

Status codes

200 OK
The request succeeded.
400 Bad Request
Invalid parameters were supplied.

Examples

Retrieve API status information

Returns various information about the current state of the API service.

HTTP method

GET api/1/status

Query parameters

None

Status codes

200 OK
The request succeeded.

Examples