VersionStatusMaturityComments
1.0-SNAPSHOTUnder testingRelease candidate 

Table of Contents

Synopsis

The HTRC Data API is a RESTful web service for the retrieval of multiple volumes, pages of volumes, and METS metadata documents.  In order support the efficient retrieval of volumes and pages in bulk, the Data API necessarily deviates from the typical RESTful design in that resources are not identified on the URL paths, but instead are sent as request parameters.

API

Retrieve Volumes

DescriptionReturns requested volumes
URL
/volumes
Supported Response Types

application/zip (normal response)

text/plain (error response)

MethodPOST
Request Types
application/x-www-form-urlencoded
Request Headers
Content-Type: application/x-www-form-urlencoded
Request BodyRequest parameters as body content.  See Parameters below
Parameters

All parameter values must be URL encoded

NameDescriptionTypeDefault valueRequiredNote
volumeIDsThe list of volumeIDs to be retrieved.stringN/AyesVolumeIDs are separated by the pipe character '|'
concatThe flag to indicate concatenation option.booleanfalsenoSee section on response format for details on its impact on the returned data
metsThe flag to indicate if METS document should be returnedbooleanfalseno 
versionThe specific version of the Data API to usestringN/AnoNot implemented.  Place holder only
Responses
HTTP Status CodeResponse BodyResponse TypeDescription
200 (ok)A binary Zip stream
application/zip
Page content and metadata of the requested volumes aggregated as a Zip stream
400 (bad request)
Missing required parameter volumeIDs
text/plain
The required parameter volumeIDs is missing in the request
400 (bad request)
Malformed Volume ID list. Offending token: ${token}
text/plain

The value for volumeIDs is malformed and the Data API cannot parse it.  ${token} will be the token that causes the error.

Example
Description

Request for volumes inu.3011012 and uc2.ark:/13960/t2qxv15, with concatenation option enabled so each volume is a single text file in the returned Zip stream.

Raw volumeIDs

inu.3011012|uc2.ark:/13960/t2qxv15

URL encoded request bodyvolumeIDs=inu.3011012%7Cuc2.ark%3A%2F13960%2Ft2qxv15&concat=true

Retrieve Pages

DescriptionReturns requested pages
URL/pages
Supported Response Types

application/zip (normal response)

text/plain (error response)

MethodPOST
Request Types
application/x-www-form-urlencoded
Request Headers
Content-Type: application/x-www-form-urlencoded
Request BodyRequest parameters as body content.  See Parameters below
Parameters

All parameter values must be URL encoded

NameDescriptionTypeDefault valueRequiredNote
pageIDsThe list of pageIDs to be retrievedstringN/AyesPageIDs are separated by the pipe character '|'
concatThe flag to indicate concatenation optionbooleanfalseno

See section on response format for details on its impact on the returned data

"concat" and "mets" cannot be both set

metsThe flag to indicate if METS documents should be returnedbooleanfalseno

"concat" and "mets" cannot be both set

versionThe specific version of the Data API to usestringN/AnoNot implemented.  Place holder only
Responses
HTTP Status CodeResponse BodyResponse TypeDescription
200 (ok)A binary Zip streamapplication/zipPage content and metadata of the requested pages aggregated as a Zip stream
400 (bad request)Missing required parameter pageIDstext/plainThe required parameter volumeIDs is missing in the request
400 (bad request)Malformed Page ID list. Offending token: ${token}text/plainThe value for pageIDs is malformed and the Data API cannot parse it.  ${token} will be the token that caused the error.
400 (bad request)Conflicting parameters in page retrieval. Offending Parameters: ${param1}, ${param2}text/plainSome request parameters have conflict. ${param1} and ${param2} will be the names of the parameters that caused the conflict. In the current version of the Data API, this is most likely caused by setting both "mets" and "concat" for page retrieval.
Example
Description

Request for the 1st, 2nd, 20th, and 30th pages of the volume inu.3011012, and the 11th, 17th, 22th, 30th, 45th, and 55th pages of the volume uc2.ark:/13960/t2qxv15, with each page being a separate text file along with the corresponding METS document of each volume in the returned Zip stream.

Raw pageIDsinu.3011012[1,2,20,30]|uc2.ark:/13960/t2qxv15[11,45,30,17,22,55]
URL encoded request bodypageIDs=inu.3011012%5B1%2C2%2C20%2C30%5D%7Cuc2.ark%3A%2F13960%2Ft2qxv15%5B11%2C45%2C30%2C17%2C22%2C55%5D&mets=true

Zip Structure Layout

The directory structure layout of the Zip stream returned from the Data API may be one of the following patterns depending on the optional parameters:

Strictly speaking, inside a Zip file the structure is flat, so there is no "directories" but only file entries.  However, in practice almost all Zip tools give the illusion of directories by leveraging the slash characters '/' in the name of each Zip entry.  For the discussion here, we follow such practice and treat the inside of a Zip file as if it were a conventional filesystem.

Suppose there are 2 hypothetical volumes in the corpus: foo.001122, which has 5 pages, and bar.ark:/13960/t123, which has 3 pages.  Both volumes also have the associated METS xml files.  The client tries to request for these 2 volumes, and also tries to request for another volume gon.000000 which no longer exists in the corpus.

Request DescriptionZip Structure LayoutExplanation of Entries

Retrieve volumes

concat=false

 

 

Because the request parameter concat=false, each volume has its own directory, and the pages and metadata documents of each volume are individual files stored under the volume directory.

foo.001122/ is a directory named after the first volume, foo.001122.  The directory name underwent a Pairtree clean process, but since it does not contain any filesystem unsafe characters, the cleaned ID looks the same as the original.

Inside foo.001122/, files 00000001.txt through 00000005.txt are the 5 pages of this volume

mets.xml will also be inside of foo.001122/ if the request parameter mets=true

bar.ark+=13960=t123/ is a directory named after the second volume, bar.ark:/13960/t123.  The directory name underwent a Pairtree clean process so that filesystem-unsafe characters such as colons ':' and slashes '/' are escaped and replaced with filesystem-safe characters.

Inside bar.ark+=13960=t123/, files 00000001.txt through 00000003.txt are the 3 pages of this volume.

mets.xml will also be inside of bar.ark+=13960=t123/ if the request parameter mets=true

ERROR.err is a file at the top level.  It is present if the request encountered some errors and the detailed error information is stored in this file.

Retrieve volumes

concat=true

Because the request parameter concat=true, each volume is a single text file, where the pages of the volume are concatenated into the file in the page order.

foo.001122.txt is the text file entry for the volume foo.001122.  The filename underwent a Pairtree clean process, but since it does not contain any filesystem unsafe characters, the cleaned ID looks identical to the original.

foo.001122.mets.xml will be present if the request parameter mets=true.

bar.ark+=13960=t123.txt is the text file entry for the volume bar.ark:/13960/t123.  The filename underwent a Pairtree clean process, so filesystem-unsafe characters such as colons ':' and slashes '/' are replaced with filesystem-safe characters.

bar.ark+=13960=t123.mets.xml will be present if the request parameter mets=true.

ERROR.err is a file at the top level.  It is present if the request encountered some errors and the detailed error information is stored in this file.

 

 

 

Retrieve pages

concat=false

The Zip stream returned from the Data API for page retrieval with the request parameter concat=false is very similar to that returned for volume retrieval with concat=false.  The difference is that only pages requested for will be included.

Retrieve pages

concat=true

Because the request parameter concat=true, the returned Zip stream is a "sequence of words" where the content of all pages from all volumes is aggregated into a single text file entry named wordseq.txt.

ERROR.err is a file at the top level.  It is present if the request encountered some errors and the detailed error information is stored in this file.

Note that there is no METS metadata returned because mixing METS metadata and page content into the word sequence could potentially contaminate the information in the word sequence file.

Additional Information

While the Data API by itself does not enforce any security mechanism for authentication and/or authorization, it is typically deployed behind an OAuth2 Servlet Filter.  A client making request to the Data API through the OAuth2 Servlet Filter must first obtain a valid OAuth2 token from the token service, and present the token as an additional HTTP request header to the OAuth2 Servlet Filtered Data API.  Please refer to "Using WSO2 Identity Server as the OAuth2 Provider for HTRC" for details on the usage.