From 2ca151971be655225c12c34fef3191fcdcd8ac38 Mon Sep 17 00:00:00 2001 From: Galen Charlton Date: Thu, 12 Jan 2023 12:38:32 -0500 Subject: [PATCH] Docs: Evergreen web services docs Signed-off-by: Andrea Buntz Neiman --- docs/modules/integrations/nav.adoc | 1 + .../integrations/pages/web_services.adoc | 92 +++++++++++++++++++ 2 files changed, 93 insertions(+) create mode 100644 docs/modules/integrations/pages/web_services.adoc diff --git a/docs/modules/integrations/nav.adoc b/docs/modules/integrations/nav.adoc index 4a4f494e81..af5aef6eda 100644 --- a/docs/modules/integrations/nav.adoc +++ b/docs/modules/integrations/nav.adoc @@ -2,4 +2,5 @@ ** xref:integrations:ezproxy.adoc[EZProxy] ** xref:integrations:patron-api.adoc[PatronAPI authentication] ** xref:integrations:rfid.adoc[RFID systems] +** xref:integrations:web_services.adoc[Web Services] diff --git a/docs/modules/integrations/pages/web_services.adoc b/docs/modules/integrations/pages/web_services.adoc new file mode 100644 index 0000000000..82205e6cc4 --- /dev/null +++ b/docs/modules/integrations/pages/web_services.adoc @@ -0,0 +1,92 @@ +::toc:: += Evergreen Web Services = + +== Existing Web Services == + +Evergreen already provides a number of web services that can be used by clients to access and modify information and implement patron and library workflows. These include: + +* The OpenSRF gateway +* The HTTP translator +* The WebSocket gateway +* An XML-RPC interface +* SRU +* unAPI services +* Web-based patron authentication and lookup services +* A mechanism for requesting that certain public catalog requests return their responses as JSON +* OpenSRF API access via XMPP + +Evergreen can also support SIP2 and NCIP via add-ons. + +=== OpenSRF gateway === + +The https://wiki.evergreen-ils.org/doku.php?id=osrfhttp:opensrf_gateway[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. + +=== HTTP translator === + +The https://docs.evergreen-ils.org/2.4/_introducing_opensrf.html#OpenSRFOverHTTP[HTTP translator] implements the https://wiki.evergreen-ils.org/doku.php?id=opensrf_over_http[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. + +=== WebSocket gateway === + +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. + +=== XML-RPC gateway === + +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. + +=== Search/Retrieval via URL (SRU) === + +Evergreen supports the https://www.loc.gov/standards/sru/[[.underline]#Search/Retrieval via URL (SRU) protocol#]. This protocol allows clients to perform an Evergreen catalog search and return results in XML. + +=== unAPI === + +Evergreen's unAPI service allows clients to retrieve bibliographic and item data in a variety of XML formats. + +=== Web-based patron authentication and lookup services === + +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. + +=== JSON output === + +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. + +=== XMPP === + +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. + +=== SIP2 === + +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. + +=== NISO Circulation Interchange Protocol (NCIP) === + +Via add-ons, Evergreen supports NCIP. NCIP can be thought of as an XML-over-HTTP moral equivalent of SIP2. + +== Evergreen API == + +=== Evergreen API documentation === + +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. + +=== Evergreen API clients === + +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. \ No newline at end of file -- 2.43.2