Evergreen Web Services

The OpenSRF gateway allows clients to make an Evergreen API request by supplying OpenSRF service, OpenSRF method name, parameters, and desired output format. The gateway can return its output in XML or JSON.

The gateway supports a request → single response mode of operation; it does not support streaming responses or OpenSRF stateful connections. Its semantics are RPC-like.

A significant third-party user of the OpenSRF gateway is the Hemlock mobile app.

The HTTP translator implements the OpenSRF-over-HTTP translator and can be viewed as a successor to the OpenSRF gateway.

The HTTP translator is designed to be a thin wrapper over OpenSRF XMPP messages. It supports stateful OpenSRF connections and both collected and streaming OpenSRF responses.

The HTTP translator uses several custom X-OpenSRF-* HTTP headers to specify the OpenSRF service to connect to and to trace messages and connections.

Responses from the HTTP translator are always serialized as JSON.

The WebSocket gateway can be thought of as a WebSocket implementation of the HTTP translator.

Responses from the WebSocket gateway are always serialized as JSON.

The XML-RPC gateway is a thin wrapper over OpenSRF method calls that supports the XML-RPC protocol. This gateway is not part of OpenSRF proper; instead, it is implemented by an Evergreen mod_perl handler.

Requests and responses are serialized as XML. The XML-RPC gateway does not support stateful OpenSRF connections or streaming responses.

XML-RPC is not commonly used nowadays; the primary known external user of the gateway is Unique Management.

Evergreen supports the https://www.loc.gov/standards/sru/Search/Retrieval via URL (SRU) protocol]. This protocol allows clients to perform an Evergreen catalog search and return results in XML.

Evergreen’s unAPI service allows clients to retrieve bibliographic and item data in a variety of XML formats.

The "PatronAPI" service is an Evergreen mod_perl handler that permits defining API endpoints for authenticating a patron login session (given username/barcode and password) and optionally retrieving fields from the patron record. PatronAPI is meant to provide an alternative to SIP2 for basic patron authentication.

The Evergreen public catalog mod_perl application normally returns HTML by combining a Perl context object with a Template Toolkit template. However, by providing a special field to the context object, public catalog request handlers can specify that their output should be returned as JSON.

OpenSRF is built on XMPP, and an XMPP client application could make OpenSRF requests directly. However, this is very rarely done outside of Evergreen client code itself.

As of version 3.9 Evergreen can act as an OAI-PMH data provider, exposing the catalog to harvesting through the OAI2 protocol.

SIP2, while not a web protocol per se, is frequently used to perform patron authentication and circulation actions. It has its origins in a serial line protocol and consequently suffers from a significant flaw: it is not encrypted by default.

Via add-ons, Evergreen supports NCIP. NCIP can be thought of as an XML-over-HTTP moral equivalent of SIP2.

Via add-ons, and using the SRU service Evergreen supports providing a Z39.50 server to allow others to search the Evergreen database via Z39.50. Z39.50 is also not a web protocol per se, but is frequently used to allow remote hosts to search bibliographic data.

OpenSRF has a mechanism for encoding documentation on the parameters and usage of an OpenSRF method. OpenSRF clients can retrieve this documentation for display.

While most Evergreen methods have at least some API documentation, overall this documentation is not complete. In addition, the primary mechanism for displaying this documentation in human-readable format, "docgen.xsl", is currently broken.

OpenSRF ships with Javascript client libraries that can be thought of as the primary means of access for web developers to Evergreen APIs.

OpenSRF also includes C and Perl clients for its services. Client code also exists in Python, PHP, and Java, but without significant documentation or community support.