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

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 collectionapi/1/objects/[alias]
List the highest rated objects in a collectionapi/1/objects/[alias]/highest_rated
View a specific objectapi/1/objects/[alias]/[pointer]
Search for objects based on their metadataapi/1/search
Search for objects by ratingapi/1/search_by_rating
Search within the full text of an objectapi/1/objects/[alias]/[pointer]/search
View an object's ratingapi/1/objects/[alias]/[pointer]/rating
Rate an objectapi/1/objects/[alias]/[pointer]/rating
View the highlighted objectapi/1/objects/highlighted
View a random objectapi/1/objects/random
Retrieve an object's spatial boundsapi/1/objects/[alias]/[ptr]/bounds
Search for objects based on their spatial areaapi/1/spatial_search
Collections
List all collectionsapi/1/collections
View a specific collectionapi/1/collections/[alias]
Comments
Search for commentsapi/1/comments
List all comments on an objectapi/1/objects/[alias]/[pointer]/comments
Post a new commentapi/1/objects/[alias]/[pointer]/comments
View a specific commentapi/1/comments/[id]
Tags
Search for tagsapi/1/tags
List all tags for an objectapi/1/objects/[alias]/[pointer]/tags
Post a new tagapi/1/objects/[alias]/[pointer]/tags
View a specific tagapi/1/tags/[id]
Vocabulary
View vocabulary term frequencies within one or multiple fields of a collectionapi/1/vocabulary/[alias]/[field]
Suggest vocabulary terms that match a given string (search suggestions)api/1/vocabulary/suggest
API Information
Retrieve API status informationapi/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

KeyRequired?DescriptionAllowed ValuesDefault Value
pageNoPage number
  • Positive integer
1
rppNoResults per page
  • Integer between 10 and 100
50
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

List the highest rated objects in a collection

HTTP method

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

Query parameters

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

KeyRequired?DescriptionAllowed ValuesDefault Value
qNoSimple string query; an alternative to the "CISO" parameters below. If this is supplied, the "CISO" parameters are not necessary.
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 number
  • Positive integer
1
rppNoResults per page
  • Positive integer between 10 and 100
50
sortNoNickname of the field by which to sort
orderNoSort 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

KeyRequired?DescriptionAllowed ValuesDefault Value
pageNoPage number
  • Positive integer
1
rppNoResults per page
  • Positive integer between 10 and 100
50
min_ratingYesMinimum rating threshold
  • Positive decimal between 0 and 1.
max_ratingYesMaximum rating threshold
  • Positive decimal between 0 and 1.
collectionsNoCollections
  • 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

Search within the full text of an object

HTTP method

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

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

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

KeyRequired?DescriptionAllowed ValuesDefault Value
aliases[]YesAliases of collections in which to search
nlatYesNorth latitude, in decimal degrees
slatYesSouth latitude, in decimal degrees
elongYesEast longitude, in decimal degrees
wlongYesWest longitude, in decimal degrees
modeNoMatching mode, in decimal degrees
  • intersect: Retrieve objects completely or partially intersecting the specified latitude/longitude coordinates
  • outside: Retrieve objects completely outside the specified latitude/longitude coordinates
  • within: Retrieve objects completely within the specified latitude/longitude coordinates
within
pageNoPage number1
rppNoResults per page50
sortNoNickname of the field by which to sort
orderNoSort order
  • asc: Ascending
  • desc: Descending
asc

Status codes

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

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

KeyRequired?DescriptionAllowed ValuesDefault Value
pageNoPage number
  • Positive integer
1
rppNoResults per page
  • Positive integer between 10 and 100
50
termNoSearch term
  • A term to search for within the comment body. Only comments containing this term will be retrieved.
collectionsNoCollections
  • A valid collection alias, or multiple aliases separated by commas, to which to limit the search.
objectsNoObjects
  • 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

KeyRequired?DescriptionAllowed ValuesDefault Value
pageNoPage number
  • Positive integer
1
rppNoResults 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

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

KeyRequired?DescriptionAllowed ValuesDefault Value
pageNoPage number
  • Positive integer
1
rppNoResults per page
  • Positive integer between 10 and 100
50
sortNoResults sorting method
  • (null): Sort descending by frequency
  • random: Randomize the results
null
termNoSearch term
  • A term to search for within the tag. Only tag containing this term will be retrieved.
collectionsNoCollections
  • A valid collection alias, or multiple aliases separated by commas, to which to limit the search.
objectsNoObjects
  • 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

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

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 api/1/status

Query parameters

None

Status codes

200 OK
The request succeeded.

Examples