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.
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-23 12:40:46 +0200 with revision 4121ef7.
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.
PAIA consists of two independent parts:
PAIA core defines six basic methods to look up, request and cancel loans and reservations, and to look up fees and general patron information.
PAIA auth defines three authentification methods (login, logout, and password update) to get access tokens, required by PAIA core.
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 (@RFC2818). 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.
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).
Every request parameter and every response field is defined with
0..1 (optional, non repeatable)1..1 (mandatory, non repeatable)1..n (mandatory, repeatbale)0..n (optional, repeatable)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=ybut the following URL query strings are invalid:
?foo1=x&foo3=y
?foo=x&foo=yRepeatable 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" : "..." } ]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...
The following data types are supported:
YYYY-MM-DD format.
[0-9]+\.[0-9][0-9] [A-Z][A-Z][A-Z]), for instance 0.80 USD.
A nonnegative integer representing the current state of a patron account. Possible values are:
1 by PAIA clients.
A nonegative integer representing the current relation between a particular document and a particular patron. Possible values are:
A PAIA server MUST NOT define any other document states.
| username | 1..1 | String | patron identifier |
| username | 1..1 | String | patron identifier |
| username | 1..1 | String | patron identifier |
| doc | 0..n | list of documents to renew | |
| doc.item | 1..1 | URI | URI of the particular item |
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.
The loginPatron method is the only PAIA method that does not require an access token as part of the query.
| 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.
| 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"
}| patron | 1..1 | string | Patron identifier |
| 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.
| 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 (TODO: document error response).
Bradner, S. 1997. “RFC 2119: Key words for use in RFCs to Indicate Requirement Levels.” http://tools.ietf.org/html/rfc2119.
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.