Patrons Account Information API (PAIA)

Jakob Voß

2012-05-28 09:20:39 +0200

Table of Contents

1 Introduction

The Patrons Account Information API (PAIA) is a HTTP based programming interface to access library patron information, such as loans, reservations, and fees. Its primary goal is to provide patron access for discovery interfaces and other third-party applications to integrated library system, as easy as possible.

1.1 Status of this document

This document is a first draft, based on a more elaborated version in German that is being implemented. The specification has been created collaboratively based on use cases and taking into account existing related standards and products such as NISO Circulation Interchange Protocol (NCIP), [X]SLNP, DLF-ILS recommendations, and ViFind ILS drivers.

Updates and sources can be found at http://github.com/gbv/paia. The current version of this document was last modified at 2012-05-28 09:20:39 +0200 with revision 868166f.

1.2 Conformance requirements

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 (Bradner 1997).

A PAIA server MUST implement PAIA core and it MAY implement PAIA auth. If PAIA auth is not implemented, another way SHOULD BE documented to distribute patron identifiers and access tokens. A PAIA server MAY support only a subset of methods but it MUST return a valid response on every method request.

2 General

PAIA consists of two independent parts:

Each method is accessed at an URL with a common base URL for PAIA core methods and common base URL for PAIA auth methods. A server SHOULD NOT provide additional methods at these base URLs and it MUST NOT propagate additional methods at these base URLs as belonging to PAIA.

In the following, the base URL https://example.org/core/ is used for PAIA core and https://example.org/auth/ for PAIA auth.

Authentification in PAIA is based on OAuth 2.0 (Hammer-Lahav and Hardt (2012)) with bearer tokens (Jones and Recordon (2012)) over HTTPS (Rescorla (2000)). For security reasons, PAIA methods MUST be requested via HTTPS only. A PAIA client MUST NOT ignore SSL certificate errors; otherwise access token (PAIA core) or even password (PAIA auth) are compromised by the client.

2.1 Request and response format

Each PAIA method is identified by a name which is appended to the PAIA core/auth base URL to get the method’s full URL. In addition there is a set of request parameters for each method. These parameters can be send as URL parameters (HTTP GET) or as form fields with HTTP request content type set to application/x-www-form-urlencoded (HTTP POST). In addition there is the special request parameter access_token which MUST NOT be sent as URL parameter (see section on access tokens for details).

The HTTP response content type of a PAIA response is a JSON object (HTTP header Content-Type: application/json;charset=UTF-8), optionally wrapped as JSONP (HTTP header Content-Type: application/javascript;charset=UTF-8).

2.2 Parameters and fields

Every request parameter and every response field is defined with

Simple parameter names and response fields consist of lowercase letters a-z only. For repeatable request parameters, consecutive numbers (1, 2, ...) must be appended to the parameter name, unless the parameter is not repeated. For instance if foo is a repeatable parameter, the following URL query strings are valid:

?foo=x
?foo1=x
?foo1=x&foo2=y

but the following URL query strings are invalid:

?foo1=x&foo3=y
?foo=x&foo=y

Repeatable response fields are encoded as JSON arrays, for instance:

"foo": ["x","y"],

Hierarchical structures are possible with a dot (.) as separator. and with objects in the JSON response. For instance the subfield/paramater item of the first field/paramater doc is encoded as

doc1.item=...

in a request or in a response as

"doc" : [ { "item" : "..." } ]

2.3 Access tokens

All PAIA methods, with loginPatron from PAIA auth as only exception, require an access token as special request parameter. The access token can be send either as request parameter in the request body (HTTP POST) or as request header:

curl -H "Authorization: Bearer vF9dft4qmT" https://example.org/core/getPatron

2.4 Error response

There are two types of errors:

Request errors
Malformed requests, failed authentification, unsupported methods, and unexpected server errors such as backend downtime etc. MUST result in an error response. An error response is returned with a HTTP status code 4xx (client error) or 5xx (server error) as defined in (Fielding 1999), unless the request parameter suppress_response_codes is given.
Document errors
Unknown document URIs and failed attempts to request, renew, or cancel a document do not result in an error response, unless there is another request error. Document errors are indicated by setting the doc.error response field.

An error response is a JSON object with the following fields, compatible with OAuth error responses:

error 1..1 string alphanumerical error code
code 0..1 nonnegative integer HTTP status error code
error_description 0..1 string Human-readable error description
error_uri 0..1 string Human-readable web page about the error

The code field is REQUIRED with request parameter suppress_response_codes. It SHOULD be omitted with PAIA auth requests to not confuse OAuth clients.

This is a preliminary, incomplete list of errors and error codes:

code error
400 invalid_request
401 invalid_client
401 invalid_grant
404 not_found Unknown method or base URL
500 internal_server_error
502 bad_gateway
503 service_unavailable
504 gateway_timeout

NOTE: See https://dev.twitter.com/docs/error-codes-responses (TODO)

2.5 Special request parameters

The following special request parameters can be added to any request:

callback
A JavaScript callback method name to return JSONP instead of JSON. The callback SHOULD only contain alphanumeric characters and underscores; any invalid characters MUST be stripped by a PAIA server. If callback is given, the response content type MUST be application/javascript.
suppress_response_codes
If this parameter is present, all responses MUST be returned with a 200 OK status code, even error responses.

2.6 Data types

The following data types are supported:

string
A Unicode string. Strings MAY be empty.
nonnegative integer
An integer number larger than zero.
boolean
Either true or false (omitted boolean values are not false but unknown!).
date
A date value in YYYY-MM-DD format.
money
A monetary value with currency (format [0-9]+\.[0-9][0-9] [A-Z][A-Z][A-Z]), for instance 0.80 USD.
email
syntactically correct email address.
URI
syntactically correct URI.
account state

A nonnegative integer representing the current state of a patron account. Possible values are:

  1. active
  2. inactive
  3. inactive because account expired
  4. inactive because of outstanding fees
A PAIA server MAY define additional states which can be mapped to 1 by PAIA clients.
document state

A nonegative integer representing the current relation between a particular document and a particular patron. Possible values are:

  1. no relation (this applies to most combinations of document and patron, and it can be expected if no other state is given)
  2. reserved (the document is not accesible for the user yet, but it will be)
  3. ordered (the document is beeing made accesible for the user)
  4. held (the document is on loan by the patron)
  5. provided (the document is ready to be used by the patron)
  6. rejected

A PAIA server MUST NOT define any other document states.

3 PAIA core

3.1 getPatron

purpose
Get general information about a patron
URL
https://example.org/core/getPatron
request parameters
username 1..1 string patron identifier
response fields
name 1..1 string full name of the patron
email 0..1 email email address of the patron
expires 0..1 date
status 0..1 account state

Additional field such as address may be added in a later revision.

3.2 getItems

purpose
Get a list of loans, reservations and other items related to a patron
URL
https://example.org/core/getItems
request parameters
patron 1..1 string patron identifier
response fields
doc list of documents (order is irrelevant)
doc.status 1..1 document status
doc.item 0..1 URI
doc.edition 0..1 URI
doc.requested 0..1 URI
doc.about 0..1 string
doc.label 0..1 string
doc.queue 0..1 nonnegative integer
doc.renewals 0..1 nonnegative integer
doc.reminder 0..1 nonnegative integer
doc.duedate 0..1 date
doc.cancancel 0..1 boolean whether an ordered or provided document can be canceled
doc.canrenew 0..1 boolean whether a document can be renewed
doc.storage 0..1 string location of the document
doc.storageid 0..1 URI location URI

For each document there must be at least a doc.item URI or a doc.edition URI. In most cases there will be an item URI for a particular copy, but users may also have requested an edition.

The response fields doc.label and doc.storage/doc.storageid correspond to properties in DAIA.

3.3 renewItems

purpose
renew one or more documents held by the patron
URL
https://example.org/core/renewItems
request parameters
patron 1..1 String patron identifier
doc 1..n list of documents to renew
doc.item 0..1 URI URI of a particular item
doc.edition 0..1 URI URI of a particular edition
response fields
doc 1..n
doc.status 1..1 document status
doc.item 0..1 URI
doc.edition 0..1 URI
doc.error 0..1 string

For each document there must be at least a doc.item URI or a doc.edition URI both in the request and in the response.

3.4 requestItems

purpose
Request one or more items for reservation or delivery.
URL
https://example.org/core/requestItems
request parameters
patron 1..1 String patron identifier
doc 1..n list of documents to renew
doc.item 0..1 URI URI of a particular item
doc.edition 0..1 URI URI of a particular edition
response fields
doc 1..n
doc.status 1..1 document status
doc.item 0..1 URI
doc.edition 0..1 URI
doc.error 0..1 string

For each document there must be either an doc.item URI or a doc.edition URI in the request and at least one of both in the response.

3.5 cancelItems

purpose
Cancel requests for items.
URL
https://example.org/core/cancelItems
request parameters
patron 1..1 String patron identifier
doc 1..n list of documents to renew
doc.item 0..1 URI URI of a particular item
doc.edition 0..1 URI URI of a particular edition
response fields
doc 1..n
doc.status 1..1 document status
doc.item 0..1 URI
doc.edition 0..1 URI
doc.error 0..1 string

3.6 getFunds

purpose
Look up current funds of a patron.
URL
https://example.org/core/getFunds
request parameters
patron 1..1 string patron identifier
response fields
amount 0..1 money Sum of all fees. May also be negative!
fee 0..n list of fees
fee.amount 1..1 money
fee.date 0..1 date
fee.about 0..1 string
fee.item 0..1 URI
fee.edition 0..1 URI

4 PAIA auth

PAIA auth defines three methods for authentification based on username and password. These methods can be used to get access tokens and patron identifiers, which are required to access PAIA core methods. There MAY be additional or alternative ways to distribute and manage access tokens and patron identifiers.

There is no strict one-to-one relationship between username/password and patron identifier/access token, but a username SHOULD uniquely identify a patron identifier. A username MAY even be equal to a patron identifier, but this is NOT RECOMMENDED. An access token MUST NOT be equal to the password of the same user.

A PAIA auth server acts as OAuth authorization server with password credentials grant, as defined in section 4.3 of the OAuth 2.0 specification (Hammer-Lahav and Hardt 2012). The access tokens provided by the server are so called OAuth 2.0 Bearer Tokens (Jones and Recordon (2012)).

A PAIA auth server MUST protect against brute force attacks (e.g. using rate-limitation or generating alerts). It is RECOMMENDED to further restrict access to PAIA auth to specific clients, for instance by additional authorization.

4.1 loginPatron

The loginPatron method is the only PAIA method that does not require an access token as part of the query.

purpose
Get a patron identifier and access token to access patron information
URL
https://example.org/auth/loginPatron
request parameters
username 1..1 string User name of a patron
password 0..n Password of a patron
grant_type 1..1 string Fixed value set to "password"

A scope parameter, as defined by OAuth 2.0 may be added in a future release of this specification to provide access tokens with different access rights (for instance read-only access).

The response format is a JSON structure as defined in section 5.1 (successful response) and section 5.2 (error response) of OAuth 2.0.

response fields
patron 1..1 string Patron identifier
access_token 1..1 string The access token issued by the PAIA auth server
token_type 1..1 string Fixed value set to "Bearer"
expires_in 0..1 nonnegative integer The lifetime in seconds of the access token

An example of a successful response:

HTTPS/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "access_token":"2YotnFZFEjr1zCsicMWpAA",
  "token_type":"Bearer",
  "expires_in":3600,
  "patron":"8362432"
}

4.2 logoutPatron

purpose
Invalidate an access token
URL
https://example.org/auth/logoutPatron
request parameters
patron 1..1 string Patron identifier
response fields
patron 1..1 string Patron identifier

The logout method invalidates an access token, independent from the previous lifetime of the token. On success, the server MUST invalidate at least the access token that was used to access this method. The server MAY further invalidate additional access tokens that were created for the same patron.

4.3 changeLogin

purpose
Change password of a patron.
URL
https://example.org/auth/changeLogin
request parameters
patron 1..1 string Patron identifier
username 1..1 string User name of the patron
password 1..1 string Password of the patron
new 1..1 string New password of the patron

The server MUST check

A PAIA server MAY reject this method and return an error response with error code 403 (forbidden) or error code 501 (not implemented).

5 Glossary

access token
A confidential random string that must be sent with each PAIA request for authentification.
document
A concrete or abstract document, such as a work, or an edition.
item
A concrete copy of a document, for instance a particular physical book.
PAIA auth server
HTTP endpoint that implements the PAIA auth specification, so all PAIA auth methods can be accessed at a common base URL.
PAIA core server
HTTP endpoint that implements the PAIA core specification, so all PAIA core methods can be accessed at a common base URL.
patron identifier
A Unicode string that identifies a library patron account.

6 References

Bradner, S. 1997. “RFC 2119: Key words for use in RFCs to Indicate Requirement Levels.” http://tools.ietf.org/html/rfc2119.

Fielding, R. 1999. “RFC 2616: Hypertext Transfer Protocol.” http://tools.ietf.org/html/rfc2616.

Hammer-Lahav, Recordon, D., E., and D. Hardt. 2012. “The OAuth 2.0 Authorization Framework.” http://tools.ietf.org/html/draft-ietf-oauth-v2.

Jones, Hardt, D., M., and D. Recordon. 2012. “The OAuth 2.0 Protocol: Bearer Tokens.” http://tools.ietf.org/html/draft-ietf-oauth-v2-bearer.

Rescorla, E. 2000. “RFC 2818: HTTP over TLS.” http://tools.ietf.org/html/rfc2818.