Zetoc Web Services SOAP Interface

Zetoc SOAP Service Definition

dc:title	Zetoc SOAP service
rslpcd:locator	http://zetoc.mimas.ac.uk/bin/soap/zetocsoap	Access point
iesr:interface	http://zetoc.mimas.ac.uk/soap/zetocsoap.wsdl	WSDL
dc:type/iesr:AccMthdList	soap
dcterms:accessRights/iesr:AuthList	ip	Authentication details - see below
rslpcd:administrator	Mimas

[The above metadata properties are according to the JISC Information Environment Service Registry (IESR) Service Entity description.]

The Zetoc SOAP interface was developed as part of the A2Z project. It is not regarded as a production standard interface into Zetoc and is not formally supported, but informal queries and problems will be answered.

New Fields in Identifier Search Response : 2008-03-07

Four new fields have been added to the Identifier Search Response. They will have values in data harvested from UK PubMed Central, i.e. Zetoc identifiers beginning with 'PM'. These fields, which are defined in the Application Profile are:

zetoc:eissn
zetoc:pmid
zetoc:doi
zetoc:copyright

Searching Zetoc using SOAP

Search Requests

There are four search requests that replicate the Zetoc Web interface. For the first three request types the start record in the result set may be specified

General Request: search over all records
Journal Request: search over journal article records
Conference Request: search over conference paper records
Identifier Request: search for a specific record using a Zetoc identifier. A Zetoc identifier may be discovered using one of the other three search requests

Search Responses

There are two search responses:

Brief Search Response: Returns the number of hits; the next position in the result set following the results returned; and an array of brief records. The brief record details correspond to the brief records returned via the Zetoc Web interface, including additionally the Zetoc identifier. A maximum of 25 records is returned. To retrieve a full set of hits it is necessary to iterate over the result set with repeated requests.
Identifier Search Response: Returns a full Zetoc record corresponding to the supplied Zetoc identifier

Metadata Properties

The metadata properties supported by the Zetoc SOAP Search Requests and Responses are defined by an Application Profile.

Authentication

Authentication to use Zetoc via the SOAP interface is controlled by DNS domain and IP check, allowing the same access as for the Zetoc Web interface. Access via Athens is not supported, human intervention not being possible.

It should be noted that the usual Zetoc Terms and Conditions apply. This means that any portal providing access to Zetoc for its end-users must first establish that they are entitled to use Zetoc.

Technical Details

Implementation

Zetoc SOAP is implemented in C++ using gSOAP. gSOAP is a set of compiler tools that provide a SOAP/XML-to-C++ language binding to ease the development of SOAP/XML Web services and client applications in C++. It has been developed by Prof Robert van Engelen and his team in the Department of Computer Science and School of Computational Science and Information Technology at Florida State University, USA (http://www.cs.fsu.edu/~engelen/soap.html). It is available under a GNU licence from SourceForge (http://sourceforge.net/projects/gsoap2). gSOAP is used to implement several major applications, including Adobe Version Cue, an innovative file-management feature of the recently unveiled Adobe Creation Suite.

Data Mapping

A Mapping from Zetoc SOAP to Zetoc data is available.

Known Problems

Request XML Issues

The Zetoc SOAP underlying software is unable to deal with some XML shorthand constructs. XML that Zetoc SOAP cannot process results in a '500 HTTP Internal Server Error' response.

Empty XML elements must have start and end tags, eg. '<dc:title></dc:title>' ('<dc:title/>' does not work)
All element names must include a namespace qualifier, eg. '<zetoc:issnOrIsbn>' ('<issnOrIsbn>' does not work)

Search Request Data Value Issues

Quoted author names in the 'creator' field do not work. Works by all authors with that surname are returned. Unquoted author names that include initials are not advised because they return works by all authors with that intial as well as all those with the surname.
Quotes round both an author name and a journal title result in a '500 HTTP Internal Server Error' response

HTTP Issues

Zetoc SOAP cannot deal with a byte order mark (BOM) at the beginning of the HTTP request content (ie. immediately preceding the XML content). A '500 HTTP Internal Server Error' response is returned. If the default behaviour of a web client is to insert this BOM, it is necessary to override this default.

Response Issues

Journal Search Request and Conference Search Request both return all journal articles and conference papers that satisfy the search
The Journal Title is missing from the string value of the 'dcterms:bibliographicCitation' property in some brief records

WSDL Issues

Several proprietary SOAP client tools are unsuccessful in using the Zetoc SOAP WSDL file. In these cases it is necessary to set up access to Zetoc SOAP manually without using the WSDL file to generate stub code. Problems include:

Several XML schemas referenced by the WSDL file are imported from external namespaces. Some SOAP clients ignore this import an attempt to find these XML schemas in the local namespace.
Some element definitions in the WSDL file are referenced from imported XML schemas (using '<element ref=...>'. Some SOAP clients expect all elements to be defined locally (as '<element name=...>').

7 March 2008