HTTP API Documentation

Versioning

The current version of our API is 1. If you don't specify the version in the URI, this is the version that will be used. Because the API may change from version to version, you are advised to include the version number, as in the examples below.

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

Our HTTP API can 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 one of the URI extensions below. XML is currently returned by default, but this may change and should not be relied upon.

URI extensionMIME typeNotes
XML.xmlapplication/xmlXML records are in the http://digital.library.unlv.edu namespace. They use XLink for cross-document hyperlinking and XML Schema for validation.
JSON.jsonapplication/json
JSONP.jsonptext/javascriptJSONP 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.

API methods

Objects

Collections

Comments

Tags

Vocabulary

API Information

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 1/objects/[alias]

Query parameters

KeyRequired?DescriptionAllowed ValuesDefault Value
pageNoPage number
  • Positive integer
1
rppNoResults per page
  • Integer between 10 and 50
20
sortNoNickname of the field by which to sort
orderNoSort 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

View a specific object

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

HTTP method

GET 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

View the highlighted object

HTTP method

GET 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

View a random object

HTTP method

GET 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

Search for objects

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 field. Note: Query parameters that are described as "filters" are applied against the query results after the query has executed; not as part of the query itself. For this reason, if any of these parameters are used, the number of results per page may be lower than what was asked for, and returned facets may be invalid.

HTTP method

GET 1/search

Query parameters

KeyRequired?DescriptionAllowed ValuesDefault Value
CISOOP[1-4]YesMatching 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]YesSearch string
CISOFIELD[1-4]YesNickname of the field in which to search
  • A valid field nickname
  • CISOSEARCHALL: Search across all fields
CISOROOTYesA valid collection alias, or multiple aliases separated by commas
pageNoPage number1
rppNoResults per page20
sortNoNickname of the field by which to sort
orderNoSort order
  • asc: Ascending
  • desc: Descending
asc
min_ratingNoFilter out results with a rating less than this. Even if 0, only objects that have been rated will be returned.
  • 0-100
max_ratingNoFilter out results with a rating greater than this. Even if 100, only objects that have been rated will be returned.
  • 0-100

Status codes

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

Examples

Search within the full text of an object

HTTP method

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

Query parameters

KeyRequired?DescriptionAllowed ValuesDefault Value
termYesSearch 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.

HTTP method

GET 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.

Examples

Rate an object

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

HTTP method

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

Query parameters

KeyRequired?DescriptionAllowed ValuesDefault Value
valueYesRating value
  • 0-100

Status codes

201 Created
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.

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 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 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

List most recent comments

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

HTTP method

GET 1/comments

Query parameters

KeyRequired?DescriptionAllowed ValuesDefault Value
pageNoPage number
  • Positive integer
1
rppNoResults per page
  • Positive integer between 20 and 100
10

Status codes

200 OK
The request succeeded.

Examples

List all comments on an object

Lists all approved comments for an object.

HTTP method

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

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

List all comments within a collection

Returns a paginated list of all approved comments in the collection with alias [alias].

HTTP method

GET 1/collections/[alias]/comments

Query parameters

KeyRequired?DescriptionAllowed ValuesDefault Value
pageNoPage number
  • Positive integer
1
rppNoResults per page
  • Positive integer between 10 and 100
10

Status codes

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

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 1/objects/[alias]/[pointer]/comments

Query parameters

KeyRequired?DescriptionAllowed ValuesDefault Value
textYesComment body
nameYesName or nickname of the person posting the comment
emailNoEmail 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 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.

Examples

List tags by frequency

Returns a list of approved tags in the system with corresponding counts.

HTTP method

GET 1/tags

Query parameters

KeyRequired?DescriptionAllowed ValuesDefault Value
pageNoPage number
  • Positive integer
1
rppNoNumber of results
  • Positive integer between 10 and 100
10
sortNoResults sorting method
  • (null): Sort descending by frequency
  • random: Randomize the results
null

Status codes

200 OK
The request succeeded.

Examples

List all tags for an object

Lists all approved tags for an object.

HTTP method

GET 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.

Examples

List all tags within a collection

Returns a list of all approved tags in a collection.

HTTP method

GET 1/collections/[alias]/tags

Query parameters

None

Status codes

200 OK
The request succeeded.
204 No Content
There are no tags within the collection.
404 Not Found
The collection with specified [alias] either does not exist or is unpublished.

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 1/objects/[alias]/[pointer]/tags

Query parameters

KeyRequired?DescriptionAllowed ValuesDefault Value
valueYesTag 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 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.

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 1/vocabulary/[alias]/[field]
GET 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 1/vocabulary/suggest

Query parameters

KeyRequired?DescriptionAllowed ValuesDefault Value
CISOFIELD[1..*]YesNick of the field in which to search; use multiple occurrences of this key (with unique numeric suffixes) to search multiple fields
CISOROOTNoAlias of a specific collection in which to search
CISOBOX1YesString 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 1/status

Query parameters

None

Status codes

200 OK
The request succeeded.

Examples