HathiTrust Rights API Phase 0

Phase0

Phase 0: Search for a single record using only OCLC number

Introduction

The Phase 0 implementation has two goals:

• A simple HTTP GET-based query interface based solely on OCLC numbers
• A javascript library that will allow easy use of returned data.

The HathiTrust javascript library, implemented as a jquery plugin, is contained in this repository.

Phase 0 Input Example

  http://mirlyn.lib.umich.edu/cgi-bin/sdrsmd?id=1&oclc=16857172

• id is an arbitrary id. It's use now is strictly in anticipation of phase 2, when we start getting requests about multiple records at once.
• oclc is the OCLC number of the record you're interested in.

Phase 0 Output Examples

The output is JSON. In particular, I'm trying to follow the JSON-RPC 1.2 spec. It's not clear where, if anywhere, things are going in the JSON-RPC world right now, but it's not a bad spec so I'm using it.

Typical output

{
  "id" : "1",
  "error" : null,
  "result" : {
    "1" : [
      {
        "oclc" : [
          16857172
        ],
        "sdr" : {
          "rights" : "full",
          "handle" : "mdp.39015030724549",
          "mburl" : "http://hdl.handle.net/2027/mdp.39015030724549"

        }
      }
    ]
  }
}

No results

Nothing went wrong, but I can't find anything that matches the criteria you sent

{
  "id": "1",
  "error": null,
  "result":
    "1": null
}

Found the metadata; no images

I found a match, but the matched record isn't available in HathiTrust. This tells you that your metadata is fine; we just don't have it.

{
  "id" : "1",
  "error" : null,
  "result" : {
    "1" : [
      {
        "oclc" : [
          16857172
        ],
        "sdr" null
      }
    ]
  }
}

Maximal output example

Note that you'll pretty much never see all of this stuff; this just lists all possible fields. (Also note that this record doesn't really exist).

{
  "id": 1,
  "error": null,
  "result":
    "1": [
      {
        "oclc": ["038257913"],
        "lccn": ["98009394"],
        "isbn": ["080582796x", "0805827978"],
        "sdr": {
          "sdrids": ["wu1000106"],
          "handle": "mdp.39015030724549",
          "mburl": "http://hdl.handle.net/2027/mdp.39015030724549",
          "rights": "searchonly" # or full
        }
      }
    ]
}

Let's look at all these values in turn.

• id is the ID you pass in
• error is either null (nothing went wrong) or non-null (something went wrong). This will be fleshed out later.
• result is a hash whose keys are id's and whose values are arrays of records that match the search criteria associated with the given id. Since we're only dealing with one ID at the moment, it will have exactly one entry.
• <id> hash value with either be null (no records match the provided search criteria) or an array of possible matches. Since we're only searching on one thing right now -- a hopefully-unique OCLC number --, there's likely to only be one record in the array.
• oclc, issn, isbn, lccn hold array of values found in this record on those indexes.
• sdr will be either null (no data in the SDR for this record) or have the structure indicated above.
• sdr.sdrids show unique identifiers associated with non-UMICH contributors (the UMICH identifier is essentially the handle).
• sdr.handle is the SDR handle for the record
• sdr.mburl is the link to the MBooks pageturner application for that record. The URL is generated algorithmically -- just concatenate http://hdl.handle.net/2027/ and the handle.
• sdr.rights one of two strings.
• searchonly indicates that you can only search
• full means you can see full text