Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

The Data API currently supports two resource types: volumes, and pages, with an optional parameter to control how the texts are aggregated.  To get resources, the client sends an HTTP “GETPOST” request to the Data API service.  The request must also have the following HTTP request header:

Content-type: application/x-www-form-urlencoded

1.2.1 Inserting the OAuth2 authentication token

The client adds an HTTP “Authorization” header to the HTTP request as follows:

Authorization: Bearer <authentication_token>

Be sure to prepend the string “Bearer “ (with a space at the end) to the authentication token before setting it to the Authorization header.  The OAuth2 protocol requires it.

1.2.2 Requesting volumes

Use the following command to request volumesTo request for volumes, set the request URL to:

https://<server>:<port>/data-api/volumes?

and the request body to a URL encoded "volumeIDs" parameter string:

volumeIDs=<volumeID_list>[&concat=true]where

<volumeID_list> := <volumeID> [“|” <volumeID> [“|”...]]

<volumeID> := <prefix>“.”<ID_string>


Example:

https://silvermaple.pti.indiana.edu:25443/data-api/volumes?volumeIDs=inu.3011012|uc2.ark:/13960/t2qxv153011012%7Cuc2.ark%3A%2F13960%2Ft2qxv15

The volumeID list consists of one or more HathiTrust proprietary volumeIDs separated by the pipe character “|”.  Each volumeID consists of a prefix, which is used by HathiTrust to identify the originating institution of the volume, followed by a dot symbol “.”, followed by a string ID that is defined by each contributing institution.  The string IDs from different institutions vary greatly, ranging from fixed-length zero-padded numeric IDs, to ARK DOIs containing filesystem unsafe characters such as colons ":" and slashes "/".

For the purpose of making a request to the Data API, the client can simply view each volumeID as a string, but may need to must perform necessary URL encoding on the volumeID so it can be safely passed as a query parameterlist so it conforms to the application/x-www-form-urlencoded content-type.  For processing the responses from the Data API, the client may find it necessary to separate the prefix and perform some string manipulation on the volumeIDs (please see more details on this in subsection 1.2.3).

The optional parameter “concat” controls whether the pages of a volume should be aggregated, as discussed in section 1.2.3.  If omitted, the default value is false.

...