Ordinary webserver requests are used as an API for JIR. The response can be obtained either using a message with XML-style markup, which is described in the present page, or using some alternative representations.
A convenient way of experimenting with the JIR server is to use the JIRCLI client, which is available at http://leonardo-gw.ida.liu.se:40087/jir-query, and here we shall use it to explain how JIR works.
JIRCLI is another web server, separate from JIR, which receives the equivalents of JIR commands, repackages them, sends them to JIR, and displays the results to the user. The repackaging provides some additional convenience for the user.
When JIRCLI is started as shown above, it shows a webpage with an input column (to the left) and an output column. The input column consists of a command field (at the top) and an attachment field.
As a first example, type or paste the following expression into the command field:
[jirpost :id bdt-002]
or, equivalently,
[jir-postpub
:server-type university
:in-journal-issn 0013-4651
:publ-year 2009
:publ-month 4
:sender jircli]
The former query is an abbreviation for the latter one, and both represent a query to JIR concerning whether an article that is published in the journal with ISSN number 0013-4651, in its April, 2009 issue may be post-published by the parallel publishing server of a university that is an affiliation of some of the article's authors. The sender parameter is intended for specifying who asks the question, and is not in active use at present.
The jirpost command uses a collection of predefined examples, such as bdt-002, whose bibliographic data are already stored in the system for demo purposes. In any case, the JIRCLI facility converts this request to the following dynamic URL request:
http://leonardo-gw.ida.liu.se:40088/[jir-postpub?server-type=university&
in-journal-issn=0013-4651&publ-year=2009&publ-month=4&
sender=jircli&a2a=xml-jir
although of course as a single line. In this simple case there is a one-to-one translation from the JIR command in the command field and the http request, but in those cases where the parameter values are complex expressions, or the attachment field is used, the correspondence is less direct.
The xml-jir parameter specifies the desired choice of format for the response, and is used if other formats are desired.
If the request is correctly formed then JIRCLI sends it to the JIR server and obtains the corresponding output. In the present case the following response is obtained:
<jir version="1.0.1">
<type>postpub-info</type>
<permit-posting>at-once</permit-posting>
<setphrase>
© The Electrochemical Society, Inc. #1. All
rights reserved. Except as provided under
U.S. copyright law, this work may not be
reproduced, resold, distributed, or modified
without the express permission of The Electrochemical
Society (ECS). The archival version of this
work was published in
<em>#2,</em>
#3.
</setphrase>
<citation-requirements>
<citation-requirement>setphrase</citation-requirement>
<citation-requirement>bibdata</citation-requirement>
<citation-requirement>publisher-cr</citation-requirement>
<citation-requirement>article-link</citation-requirement>
</citation-requirements>
<caution-codes>
<caution-code>+/-52</caution-code>
</caution-codes>
<caution-phrases>
<caution-phrase>
Link to URL for specific article on publisher's server is required
</caution-phrase>
</caution-phrases>
<base-information>
<server-type>university</server-type>
<issn>0013-4651</issn>
<journal>Journal of the Electrochemical Society</journal>
<publisher>Electrochemical_Society</publisher>
<pub-code>romeo-0090</pub-code>
</base-information>
</jir>
The response contains a number of parameters that provide the information that may be needed by the application program. The meanings of these parameters are specified in the tab for Results in XML. In particular, the permit-posting parameter provides the main part of the answer, namely, whether the article in question may be posted now, not at all, or not yet but during a particular month. Other parameters specify various aspects of how the article is to be presented. The base-information parameter is not operationally useful, but shows the information that JIR used for compiling the answer, in order to facilitate double-checking the answers.
In those cases where the publisher in question requires a particular "set phrase" to be used on the cover page of the author-published version of the article, this is indicated by the occurrence of the symbol setphrase in the required-citation parameter. The set phrase itself is provided using the <setphrase> component of the response. The contents of component presently uses a particular notation for representing slots where article-specific information is to be substituted. Expressions beginning with a pound sign are intended to be substituted as follows:
As a temporary convention, the symbol // may appear in the setphrase in order to indicate a new-paragraph break.
The JIRCLI facility makes syntactical checks on the input commands, which of course is necessary as it translates those commands to http requests. However, these checks are not complete, and some syntax errors will just cause JIRCLI to reject the input and return a blank page in the results column. Diagnosed syntax errors are displayed using an error outcome record with the same general format as the result records.
For errors that are detected in the JIR server there is a similar situation: some errors are trapped and diagnosed and the diagnosis is presented in the output column of JIRCLI; other errors are not trapped and cause JIR to return an error message to JIRCLI, which in turn tries to resolve the situation.
Both the JIR server and the JIRCLI server are robust towards errors, so that even in the worst case they will simply proceed to honoring the next incoming request. We do not know of any input that will bring down any of these servers.
The help option on the JIRCLI webpage will mention additional services even if sometimes they have not yet been included in the present documentation.