A NISO Recommended Practice is a recommended "best practice" or "guideline" for methods,materials, or practices in order to giveguidance to the user. Such documents usually represent aleading edge, exceptional model, or proven industry practice. All elements of RecommendedPractices are discretionary and may be used as stated or modified by the user to meet specific needs.

This recommended practice may be revised or withdrawn at any time. For current information on thestatus of this publication contact the NISO office or visit the NISO website (www.niso.org).

All rights reserved under International andPan-American Copyright Conventions. For noncommercial purposesonly, this publication may be reproduced or transmitted in any form or by any means without prior permissionin writing from the publisher, provided it is reproduced accurately, the source of the material is identified, andthe NISO copyright status is acknowledged. All inquiries regarding translations into other languages orcommercial reproduction or distribution should be addressed to:

a SUSHI clientmakes a request to aSUSHI Serverand how the server responds to the client.

During the development of a SUSHI client, it is often time-consuming and, in general, difficult to gettest credentials on the servers that the client intends to harvest usage from. In some cases access to theserver is restricted due to the sensitive nature of the usage data.Some servers restrict the number ofrequests that can be submitted in a 24 hour period by a client,

limiting the amount of testing. Andeven if servers do not restrict access, repeated tests on the part of a client may also add unnecessarystrain on the server.

The SUSHI Standing Committee, whose role is to maintain the standard, promote its usage, andeducate and assist implementers, proposed that aSUSHI Servers Working Groupbe establishedtodevelop a recommended practicefor howContent Providerswouldprovide access to theirSUSHIServers

in a “test” mode. This proposal was approved by theBusiness

Information Topic Committeein January 2011.

This recommended practice is the SUSHI Working Group’s deliverable.It describes how the serverwould be expected to behave normally (e.g. issuing errors when appropriate and responding withreports when appropriate); however, rather than delivering live usage data, theywould just

deliversample reports.

The expectation is that developers of clients would be able to get test credentials withminimal effort and that authentication requirements for the server running in test mode would berelaxed.

The overall objective is to make it easier for SUSHIClients to be developed by reducing andeliminating common roadblocks. The advantage to theContent Provider

is thatitspends

less timesupportingClient Developers.Successful implementation of SUSHI means more accurate andtimelier

reporting.It is also in the Content Provider’s interest forlibrarians to have easy access to thenecessary usage statistics to make informed collection development

decisions.

NISO TopicCommittee Members

TheBusiness Information

Topic Committee had the following members at the time it approved thisRecommended Practice:

[to be added by NISO after approval]

NISO RP-13-201x

DRAFT FOR TRIAL USE

v

NISOSUSHI Servers

Working Group Members

The following individuals served on the NISOSUSHI ServerWorking Group, which developed andapproved this Recommended Practice:

Oliver Pesch (chair)

EBSCO Information Services

Paul Needham

Cranfield University

Bob McQuillan

Innovative Interfaces, Inc.

Xiaochun Xing

Swets Information Services

John Milligan

ScholarlyIQ

Acknowledgements

The

SUSHI Servers

Working Groupwishes to acknowledge those outside the formalworking group

membership who contributed to this effort.

[to be added to final documentas needed]

Trademarks, Services Marks

Wherever used in this standard, all terms that are trademarks or service marks are and remain theproperty of their respective owners.

NISO RP-13-201x

vi

DRAFT FOR TRIAL USE

NISO RP-13-201x

DRAFT FOR TRIAL USE

1

Section 1:

Introduction

1.1

Purpose and Scope

These recommended practices are intended to promote the adoption of the SUSHI standard bymaking it easier fordevelopersto create SUSHI client software—applications that can harvest andanalyze COUNTER reports.

This objective will be met byproviding a series of recommended practices that Content Providers canfollow to improve the accessibility of their SUSHI Servers

toClient Developers. Accessibility will beimproved by providing a test version (or test mode) for the SUSHI Sever; bysimplifying oreliminating the need for a SUSHIClient to be registered before it can access the test version of theSUSHI Server; and

by providing technically equivalent responses to SUSHIRequests.The testversion is not expected to respond with actualcustomer data.

The goal is to remove as many barriers as possible for the developers

so that they can more rapidlydevelop and test the fundamentals of their client software using test data.

This document acknowledges that final testing

of any client can only

be performed on production dataand

forthis,

the SUSHI Server will need to impose the security measuresneeded to protect customerdata.

1.2

Terms and Definitions

The followingterms,

as used in this recommended practice, have the meanings indicated.

Term

Definition

Client Developer

A person who is creating an application that will act as aSUSHIClient that will retrieve information from the SUSHIServer.

ContentProvider

The organization that provides COUNTER usage statistics onbehalf of apublisher. For the purposes of this document, this isthe organization responsible for the SUSHIServer andproviding a test instance or test mode for that server.

COUNTERreport

A usage report formatted to the specifications set out in theCOUNTER Codeof Practice

that is delivered as the payload ofthe SUSHIresponse. With SUSHI, the COUNTER report is anXML document formatted to the COUNTER schema.

exception

In the context of SUSHI, an element within the SUSHI Schemafor the SUSHIResponse used to report to the client an error orother condition that indicates there were issues with completingthe request.

NOTE:

An exceptionmay be issued even though

aCOUNTERreportis includedwith the Response;

it could indicate that theResponse differs from theRequest.

production server

An instance of a SUSHIServer used to retrieve actual customerusage data.

An instance of the SUSHIServer (or an operational mode) thatcan be used to retrieve test data. Thetestserver will notdeliveractual data and will have less rigid authentication requirements.

NISO RP-13-201x

DRAFT FOR TRIAL USE

3

Section 2:

Expectations for SUSHI Servers

2.1

Registration Requirements for Client Testing

2.1.1

Requirement for Registration

TheContent Provider

may choose to require the registration of test clients

to controlaccess and offerdebugging

assistance by being able to identify the specific client making the request.If

the client isidentified in the request via the Requestor ID, then theContent Provider

knows who to contact ifthere

isa problem.

2.1.2

Registration process

If theContent Provider

chooses to requirethe developer to register the client,registration should beasimple process managed by either an e-mail request or a web form.

In aRequest the developer would declare the

intent to access the test version of the ContentProvider’s SUSHI Server and would be expected to provide thecontactname, contact e-mail,organizational affiliation, the IP address of the test client, and a short description of the project.

In response the Content Provider wouldsend the developer the URL to the test server, a Requestor

ID, the Customer

ID to use,

and any other special instructions.

The registration process should take no longer than one business day.

2.1.3

Registration Instruction Included onSUSHI Server Registry

Registration instructions for developers should be made available through the SUSHI Server Registryas part of the instructions. The SUSHI Server Registry will include an entry forTest ServerInstructions.The instructions

could take

the form of detailed instructions, a link to a separate webpage

with instructions,

or an e-mail address

for inquiries.

2.2

Relationship Between the Test Server and the Production Server

AContent Provider

may choose to offer a separate SUSHIServer for testing. This is acceptableprovided that server is technically equivalent to the production server. Following are points ofclarification.

2.2.1

The Test ServerMayBe aSeparateInstance

The Content Provider, at its option, may choose to keep a separate instance of

itsSUSHI Server fortesting

purposes.In the casewherethere is a separate instance, the URL to the test server should beprovided in the SUSHI Server Registry or if the client must be registered,the URLmay be providedto theClient Developer

at the time the client

is registered.

2.2.2

Test ServerMust beTechnically

Equivalent

The

testserver,

or the production server operating in testmode,

must

operate in a manner that istechnically equivalent to the production server.Specifically, it must:



Support the

same reports as the production server



Create SUSHIResponses that are structurally equivalent to the production server



Create COUNTER reports that are structurally equivalent to the production server

NISO RP-13-201x

4

DRAFT FOR TRIAL USE



Respond to error conditions in the same manner as the production server

2.2.3

Test ServerDoesNot

Need To Offer Equivalent Data

The test server must offer representative usage data for inclusion in theCOUNTER reports; however,this data does not need to match production data.The purpose of the test server is to help aClientDeveloper

in testing system functionality and notto retrieve live data.

2.3

SecurityConsiderations

If the Content Provider offers a test mode that is open to anyone (no registration required),

mustalsoemulatethe same methods as the production server so that theClient Developer

can make thenecessary customizations to the client software before accessing the production server.

2.4

Operational Considerations

2.4.1

Requestor ID and Customer ID

If the Content Provider requires the developer to register the test client before access is granted, thenthe Content Provider will inform the developer of the Requestor ID and Customer ID to use fortesting.

If the Content Provider offers a test mode that is open to anyone (no registration required), thefollowing values would be expected in the SUSHI Request to use the server’s test mode:

Requestor ID = test

Customer ID= test

2.4.2

ReportDefinitions

Theclient would be expected to request valid COUNTER reports. The server would be expected toreturn a representative report if the report is supported or

Theclientis expected to provide a valid date range in the request. The server would respond with arepresentative report if the dates are within the supported range or the server would respond with thestandard error messages for the standard server conditions, such as: “No Usage Available forRequested Dates”

if the dates are not within the supported range or“Invalid Date Arguments”

if thebegin

date

is greater thantheend

date.

(See section 6.2.3, Exceptions and Errors, in the SUSHIstandard for more onstandard

error reporting.)

2.4.4

COUNTER ReportsTo Be

Returned in the Response

TheContent Provider

can, at its option, respond with pre-settestreports for each of the supportedCOUNTERreports.

NISO RP-13-201x

DRAFT FOR TRIAL USE

5

Each supportedCOUNTERreport should provide sufficient data to demonstrate the nature andstructure of the response; specifically:



If multiple metric types can be provided, then each metric type should be represented in theresponse.



If multiple databases

and journals can be provided, then the report should include multipleentries.



If a request is for multiple months, then the response should include multiple months of datafor each item in the report.



If titles in the report don’t all have

identifiers, then itisrecommended to include a sample oftitles with and without identifiers.

2.4.5

Error Reporting

When the test server encounters an error condition that results in anexception

being returned in theSUSHI Response, the server shouldinclude

sufficient contextual information in either theMessage

ortheData

elements to assist theClient Developer

in diagnosing the error.For example, if a report isnot supported, the Exception Number would be “3000”andthe message could say that “Report namesubmitted (<name-submitted>) is not valid or not supported by this server.”

2.5

Logging of Client Activity on the SUSHI Server

It is recommended that the SUSHI Server logtestSUSHI Requests to assist with debugging both theserver and the clients. By recording thetestrequest as well as the server’s response to that request(including errors generated by the request) theContent Provider

can assistClient Developers by beingable to spot errors in the

clientrequests.

NOTE:

This recommended practice sets no expectation that requires theContent Provider