The Summon Availability API is a service that allows retrieval of catalog item availability statuses. The service allows batch requests for efficiency. This means only one service call is necessary for a page containing multiple catalog items. The Availability API is not an authenticated service. The response format is available in three flavors: XML, JSON and streaming JSON. Since availability status calls can take a relatively long time, the streaming JSON format allows availability statuses to appear on the page as soon as they are retrieved, even if there are still other statuses being retrieved. The combination of batch requests with streaming responses allows for a fairly responsive feel to the UI while only tying up one valuable browser thread.
The base URL for the Availability API is http://api.summon.serialssolutions.com/availability/<client_key> where <client_key> is a valid Serials Solutions client key. The Availability API will return availability statuses for the catalog items owned by the client identified by the given client key.
The Availability API honors two specific HTTP headers, in addition to the standard required HTTP headers such as Host, and Date. The headers that impact the Availability API are the following:
Accept- The accept header determines the output format of the response, and acceptable values are
x-summon-session-id- As with all summon requests, the Availability API supports the Summon session id header which allows separate API calls to be tied to individual user sessions. A custom session id may be provided if the UI already tracks a session for the user, or if a custom session ID is not provided on the first call to the API, the API will generate and return a session ID. The session id should be passed with all future requests made in the same user session.
The Availability API accepts one parameter:
s.id. There maybe one or more instances of the
s.id parameter. Each parameter may contain one availability ID. The availability IDs may be retrieved from the
availabilityId field in the documents in a Search API response.
The response contains a list of availability items corresponding to the
s.id parameters given. An availability item may have multiple availability statuses if there is more than one catalog item for a given availability ID. The basic XML and JSON fromats produce the entire response as a single element or object respectively. The streaming JSON response type returns each availability item as a single JSON object, and each each object is separated by a linefeed ('\n') character.
The availability service aggregates many different availability types, and as a consequence the fields that are returned may vary from library to library. Regardless of the disparate formats, the API will try and provide a "best guess" at what the display string should be for a given catalog item. The "best guess" will appear in the
displayString field. If the
displayString is not present for a given catalog item, then it is probably best do display a link to the catalog directly to find the item status that way. The other fields that that the Availability API returns include:
status- The status of the item. One of '
not available', '
possibly available' or '
statusMessage- A status message provided by the library.
location- The library or storage where the item is located.
callNumber- The item call number if applicable.
locationString- A string providing possible location and / or call number information.
displayString fails to satisfy the requirements of a particular UI, the other fields may be used to algorithmically generate a custom availability display string. If you choose this option keep in mind that these fields are not guaranteed to appear in all availability items, and the exact content of each field varies from library to library.
The streaming JSON format is the content of the
availabilityItems array from the basic JSON format, with each object separated by a linefeed ('\n').