SUSHI FAQs: Content Providers & Consolidators
Last updated July 8, 2010
- How does the SUSHI protocol work?
- What is the relationship of the SUSHI standard (Z39.93), the SUSHI schema, and the SUSHI WSDL?
- Where can I find the SUSHI schemas and WSDL?
- How often is the SUSHI schema updated?
- What are the various technologies involved with SUSHI implementation?
- What is the difference between the client and the server implementation of SUSHI?
- What variable information has to be supplied in a SUSHI (client) request?
- What variable information has to be supplied in a SUSHI (server) response?
- If I am a content provider, what are the major basic steps involved into SUSHI implementations?
- If I am a system developer, how do I implement the client side of SUSHI?
- Are there tools to help developers get started?
1. How does the SUSHI protocol work?
The image below ilustrates how the protocol works.
2. What is the relationship of the SUSHI standard (Z39.93), the SUSHI schema, and the SUSHI WSDL?
The SUSHI standard is the high-level framework in which the SUSHI Schema, SUSHI WSDL, and COUNTER reports operate. The SUSHI WSDL describes, with a high level of abstraction, how the client and server sides of the web services transaction will interoperate. The WSDL gives information referring to the lower level, more detailed and specific information about the transaction, which is described in the schema. The schema is the XML code that is used to perform the SUSHI operation. Variable information in the schema is modified at the time the code is executed. The COUNTER XML report is the actual payload of the transaction.
3. Where can I find the SUSHI schemas and WSDL?
The latest SUSHI schemas and WSDL are available at the NISO SUSHI schema webpage. Additional resources can be found on the main SUSHI website: www.niso.org/workrooms/sushi.
4. How often is the SUSHI schema updated?
Changes to the schema that meet the standard's definition of allowable changes will be made as needed, but no more than annually. The protocol is intended to be robust enough to accommodate new COUNTER reports and releases without any changes to the SUSHI schema.
5. What are the various technologies involved with SUSHI implementation?
- What is SUSHI protocol? The SUSHI protocol is a standard client/server web services utilizing a SOAP request/response to retrieve the XML version of the COUNTER report.
- What are Web Services? Web services are server-based software applications that are accessed through a network and provide information or other responses to standard, XML-based messages. They are platform-, application-, and language-independent; services are akin to collections of software functions that can be called remotely by any application that conforms to a specified protocol. The inputs, outputs, formats, and parameters of a web service are typically defined by a WSDL and may be registered in a Universal Description, Discovery, and Integration (UDDI) directory. SOAP is a particular Web services message protocol that is a W3C Recommendation. SOAP messages are frequently, though not necessarily, used to interact with a Web service. A real-world example of a web service is Google's SOAP Search API, which a developer can use to incorporate Google search functionality into third-party software. More on Web services.
- What is WSDL? WSDL (Web Service Description Language) is an XML format used to completely describe a Web service. The WSDL defines the operations or functions the service provides, the formats and parameters used to access them, the transport mechanism (e.g., SOAP) used to send and receive input and output messages, and the Web address(es) where the service is located. A complete WSDL can be used to create a functional client that can send requests to the WSDL's corresponding service and receive its responses.
- What is SOAP? SOAP is an XML-based protocol used for exchanging messages between two networked computers. The communication occurs through HTTP, just like a Web browser. The SOAP specification is a Recommendation of the World Wide Web Consortium (WC3).
- What is an ERM? Electronic Resource Management (ERM) software is developed for the specific purpose of managing a library’s electronic resource collections and subscriptions. ERM systems, which can be either standalone or directly tied to a library system vendor’s other modules, usually track the life cycle of an electronic resource. This can include management areas such as: access, acquisitions, licensing, cost, invoicing, workflow, trial use of electronic products, and resource usage.
Many of today’s ERM systems are based on the Digital Library Federation’s Electronic Resource Management Initiative report.
- What is an XML schema? An XML schema is “is a description of a type of XML document, typically expressed in terms of constraints on the structure and content of documents of that type, above and beyond the basic syntax constraints imposed by XML itself. An XML schema provides a view of the document type at a relatively high level of abstraction”. [Source: XML schema. (2006, July 6). In Wikipedia, The Free Encyclopedia. Retrieved July 27, 2006.]
- More on XML
6.What is the difference between the client and the server implementation of SUSHI?
The SUSHI client application packages a request for a usage statistics report and sends it to a compliant SUSHI server. The SUSHI server parses the incoming request from the client, including the specific report requested and the identity of the customer for whom data is to be retrieved. A server may either have prepackaged customer’s data ready for immediate delivery or it may search its data store contemporaneously with the request and create the response ad hoc. In either case, the server returns the requested report in XML format.
7.What variable information has to be supplied in a SUSHI (client) request?
In the current release of SUSHI (ANSI/NISO Z39.93-2013), the mandatory variable information to be supplied in a SUSHI request is:
- Requestor ID
- Use the domain of the service making the request. Examples:
- Serials Solutions is making the request on behalf of a client, use "http://www.serialssolutions.com/"
- Cornell uses III client software installed locally, use "http:://www.iii.com"
- CustomerReference ID (which may or may not be the same as the Requestor ID)
- Name of the report being requested
- Release (i.e., version) number of the report being requested
- Begin date of the report being requested
- End date of the report being requested
There are additional variable fields that can be supplied in a report request which are recommended or optional that are not included in the list above. Refer to the standard for the complete list of available fields.
8. What variable information has to be supplied in a SUSHI (server) response?
In the current release of SUSHI (ANSI/NISO Z39.93-2013), the mandatory variable information to be supplied in a SUSHI response is:
- Requestor ID (repeated from request message)
- Report name, release, and dates (repeated from request message)
- Report (the actual XML payload with the report data)
- Exceptions (only if applicable, any exception or error messages)
9. If I am a content provider, what are the major basic steps involved into SUSHI implementations?
SUSHI's role in this environment is merely the delivery of a usage report from a content provider to a library. The most common report being delivered is COUNTER Journal Report 1; however, Database report 1 is also of interest to many.
If you review the COUNTER Code of Practice for Journals and Databases (http://www.projectcounter.org) you will see more details on the reports and the expectations for reporting. One thing you will note is that reporting of full-text downloads is the responsibility of the site actually delivering the full text. Typically a federated search engine assists users in finding and retrieving things held at other sites; therefore, they are not actually hosting the content or directly delivering it. This means that, from a technical perspective, a federated search engine would not be responsible for delivering COUNTER reports. However, this does not prevent them from providing usage reports in COUNTER format and allowing those reports to be delivered by SUSHI.
The first place to start would be in analyzing how you are capturing your usage statistics for your site. Can you produce a COUNTER report today? If not, that would be the place to start.
The next step would be to produce that COUNTER report as XML using the COUNTER schema -- we would recommend you use the latest schema that appears on the NISO website.
Once you have the ability to produce a COUNTER report, the next step would be to determine a simple security model. Your customers will most likely want to be sure that you don't allow unauthorized people to access their usage. The security model could be as simple as restricting which IP addresses are eligible to request usage for a particular customer.
Now you can produce a COUNTER report in XML format and you have a simple security system in place you can start on the SUSHI implementation.
Ideally, you will have created some kind of a service layer for your reporting services. For example, your user interface for your COUNTER reports collects the specific parameters, such as which report and what date range and customer code from the user, then passes this to your COUNTER web service that pulls the data and formats and returns the report. If you have this in place, then SUSHI becomes fairly straightforward:
- Create a SUSHI web service that captures the SUSHI request
- Analyze the request and verify the following (return errors as appropriate):
- verify that you want to allow that client to request usage (e.g., a check of their IP)
- verify that the customer code is valid
- verify that you can deliver the requested report
- verify that the date range is valid
- Call your reporting service to fetch the requested COUNTER report for the customer and date range specified
- Assemble the SUSHI Response inserting the COUNTER report or appropriate error code.
- Send back the response.
The above assumes you have some experience in writing web services using .NET or JAVA. If not, you may want to look for resources to help bring you up to speed on that first.
Other recommended resources:
- Getting Started with SUSHI: For Developers of SUSHI Servers
- EBSCO's SUSHI Software Development Kit (SDK) [for servers]
10. If I am a system developer, how do I implement the client side of SUSHI?
The first place to start is the Getting Started guide for developers of client applications which can be found at: http://www.niso.org/workrooms/sushi/start/clienta. This document will help you understand and organize the work to do to create your own client. It also recommend reviewing the MISO client, which is a freely available SUSHI client that comes complete with source code (http://code.google.com/p/sushicounterclient/).
11. Are there tools to help developers get started?
On the SUSHI website you can find links to an extensive set of tools on the “SUSHI Tools” page (http://www.niso.org/workrooms/sushi/tools/). Below is a summary of some of these tools.
- EBSCO's SUSHI Software Development Kit (SDK)
This SUSHI SDK (software development kit), from EBSCO’s developer Richard Carruthers, is now available on Google Code and is available for use under the new BSD license. The project description is: "This SDK includes .Net classes that will facilitate working with COUNTER 3.0 data and SUSHI 1.6 services. Whether the intended solution is a SUSHI client or server, these classes will provide the groundwork to allow developers to focus on the logic rather than implementing the standard."
- MISO: Serials Solutions' Open-Source Code for SUSHI Client
The Serials Solutions open source SUSHI client code will enable libraries to build consistent, stable, and standards-based tools. It is the first release of what the maintenance committee hopes will be many open source toolkits for libraries.
- How to Start Building a SUSHI Service
This draft document by Tommy Barker, Software Engineer, IT & Digital Development, at the University of Pennsylvania Library, is a work in progress -- and a valuable tool for those interested in getting started with building a client. As it states in the beginning, "Before building a SUSHI client, it is a good idea to first test the service with reliable third party tools to see if it is working properly. Additionally, you will have a sample request and response to help model your client." This aims to show how.
- Penn Open Source SUSHI Client April 3, 2009: The University of Pennsylvania recently put together a client to harvest SUSHI1.6/COUNTER3.0 data. We have decided to release it to the Sushi community under the Apache 2 License. Currently it is a beta release and only has been tested against Project Euclid. So as SUSHI services become available, we suspect we will have to address several bugs. It is written in Java, but since many languages target the JVM, you should be able to use other languages such as Ruby, Python or Groovy.
- The project is here: https://labs.library.upenn.edu/SushiToolkitDocs/site/.
- We also have a web interface built on the toolkit to create simple spreadsheet reports here: https://labs.library.upenn.edu/SushiWebClient/SushiCall