Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.
1.0-SNAPSHOTUnder testingRelease candidate 



Table of Contents


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.


Retrieve Volumes

DescriptionReturns requested volumes
Supported Response Types

application/zip (normal response)

text/html (error response)

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

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
HTTP Status CodeResponse BodyResponse TypeDescription
200 (ok)A binary Zip stream
Page content and metadata of the requested volumes aggregated as a Zip stream
400 (bad request)
<p>Missing required parameter volumeIDs</p>
The required parameter volumeIDs is missing in the request
400 (bad request)
<p>Malformed Volume ID list. Offending token: ${token}</p>

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


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


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


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.