RIOJA Journal-Repository APIs

Draft version 1, August 2007. Notes and history.

Contents:

Introduction
Typical workflow
API details
Repository APIs
- getRepositoryInfo: Get information about the repository
- validateAuthor: Author validation
- getMetadata: Metadata exchange
- setStatus: Journal status change notification
- getStatus: Get journal status from repository
- getTrackbacks: Get repository trackbacks
- getStatistics: Get repository statistics
- getCurrentPaperInfo: Get current state of paper
Journal APIs
- getJournalInfo: Get information about the journal
- getStatus: Get submission status within the journal
- submit: Submit to journal from repository
FAQ
- Why not use OAI?

Introduction

This page described XML-base APIs for the exchange of data between digital repositories and journals to facilitate overlaying of academic journals on separate digital repositories. The repository is assumed to provide the registration, awareness and archiving functions of a journal. The journal is assumed to provide only the certification (peer review) and additional awareness functions. All copies of a paper are stored in the repository, from the original submission to the published version and beyond. The repository can tag papers with their status, so end users can if desired filter papers so that they only see submitted, accepted or published papers as they prefer. The journal tracks different versions of the repository paper, and applies its final "published" quality stamp to one particular "final" paper version. The repository may however allow updates to a paper after publication, allowing easy-access to a corrected version as well as the "published" version.

Typical workflow

Author submits paper to repository
Repository optionally offers link to submit to a registered RIOJA-enabled journal, or author manually visits journal website
Author provides repository ID to the journal (or this is provided by optional API)
Journal extracts metadata from repository, displays summary to author, and confirms submission
Journal checks repository paper status at regular intervals; once accepted by the repository the journal continues as below; if the paper instead becomes rejected or withdrawn by the repository the journal automatically rejects the paper.
Optional API informs the repository that the paper is under consideration by the given journal (so the repository can report the status, and/or prevent submission to other journals)
Journal proceeds with normal peer-review process: appointing editors, referees, etc, who write reports based on links to the paper on the repository
Author may update paper on the repository in response to referee/editor feedback and journal re-submission can take place
Journal finally either accepts or rejects the paper. If rejected optional API informs the repository.
On paper acceptance the journal assigns a journal ID to the paper, lists it in its lists of accepted papers, optionally notifies the repository of the publication information, and makes metadata available by standard OAI interface
Paper has page on the journal site giving metadata of published version, version-specific link to the published paper on the repository, and optional links to any future modified versions on the repository.

In addition there are optional APIs allowing the journal to display trackback and download statistics for the paper.

Journal and repository configuration

Two general information APIs provide information about the repository or journal. This should make it easy to support additional repositories from journal software by providing just one URL - the URL of the RIOJA API on the repository. Similarly additional journals can be supported by the repository by supplying just the URL of the RIOJA API on the journal.

API details

APIs operate by HTTP POST or GET calls to a URL which returns an XML file. The input contains an apiName parameter that determines which API is being called. The response contains information in various formats depending on the API, plus a standard resultStatus element, which is either OK, notImplemented, invalidID or error. The optional element errorMessage can specify any text error message. Some APIs must be implemented, some are optional (can return notImplemented).

The APIs are summarized below along with sample xml. See also the full .xsd schema files:

rioja-types.xsd - various general type definitions
riojaRepOut.xsd - repository API output
riojaJrnlOut.xsd - journal API output

getRepositoryInfo: Get repository information

Input: none, e.g.

 http://someurl.com/rioja?apiName=getRepositoryInfo

Output: repositoryInfo structure with information about the repository. e.g.

<rioja-repository-output>
  <resultStatus>OK</resultStatus>
  <repositoryInfo>
     <repositoryId>arXiv.org</repositoryId>
     <repositoryName>arXiv</repositoryName>
     <supportedAPI>getRepositoryInfo</supportedAPI>
     <supportedAPI>getMetadata</supportedAPI>
     <supportedAPI>getStatus</supportedAPI>
     <supportedAPI>setStatus</supportedAPI>
     <APIVersion>1.0</APIVersion>
     <paperIDformat>[0-9]{4,6}\.[0-9]{4,6}</paperIDformat>
     <homepage>http://arxiv.org</homepage>
     <submitPage>http://arxiv.org/help/submit</submitPage>
     <paperIDbase>arXiv:</paperIDbase>
  </repositoryInfo>
</rioja-repository-output>

RIOJA-R1: Author validation

Repositories typically fulfil the preliminary filtering and author validation requirements of a journal. The RIOJA validation API is designed to ensure that someone submitting a repository paper to a journal is actually the original author of the paper. The chosen method is via email validation: the journal author account will typically validate a submitter's email, and hence know that it is valid. The repository will likewise have at least one validated email associated with each submitted paper. For privacy/spam avoidance issues the RIOJA API does not include output of associated email addresses; instead the repository can validate an email and then ask the journal "is this email associated with that paper?". This is sufficient to prevent malicious third-parties or spam-bots submitting a paper that they are not an author of.

validateAuthor Required repository API

Input: comma-separated list of email addresses and repository paperId. e.g.

 http://someurl.com/rioja?apiName=validateAuthor&paperId=1234.5678&email=email_1,email_2,email_3

Output: validEmail list of the email addresses associated with that paper in the repository. e.g.

<rioja-repository-output>
  <resultStatus>OK</resultStatus>
  <validEmail>email_1</validEmail>
  <validEmail>email_2</validEmail>
</rioja-repository-output>

If no paper is associated with the paper the returned list can be empty. resultStatus can be invalidID if the paper does not exist.

RIOJA-R2: Metadata exchange

Although all copies of the paper reside on the repository, the journal will require the metadata: authors, title, abstract, etc. In general it will need this for several versions of the paper: the version originally submitted to the journal, versions after author-responses to referee reports, the final version accepted by the journal. The published-version metadata will ultimately also be available from the journal via standard OAI APIs. However any OAI implementation on the repository will not in general provide enough version-specific information for overlaying a journal, so the RIOJA getMetadata repository API is provided to supply this information. It should be available from the moment paper submission to the repository is complete, even if the paper is not yet validated or made public on the repository. The metadata includes as status tag for each version so that the journal can use to ascertain the status of a paper. The journal should update metadata once status of the latest version changes to public (typically checked once or twice a day after submission), as repository may not provide valid paper URLs until this point. version metadata must include title and author information and at least one paper URL once the status is public. Some repositories may make all submissions from validated authors immediately public.

The repository can use non-public internal paper IDs for use by RIOJA. In this case the publicId metadata element should be set to the public ID as soon as the first version of the paper status changes to public. Subsequent calls to RIOJA API can use either temporary ID or public ID; they should therefore be distinct. The journal may want to use the publicId as part of its journal paper ID once the paper is accepted.

Title, abstract and comments fields can contain latex (contained in latex element), or standard text with optional html-compatible embedded formatting elements b, i, u, ovl, sub, sup, scp, tt (compatible with the Crossref standard).

getMetadata Required repository API

Input: repository paperId. e.g.

 http://someurl.com/rioja?apiName=getMetadata&paperId=astro-ph/0702600

Output: paperMetadata structure with metadata for all versions of the paper in the repository, links to repository file version, etc. e.g.

<rioja-repository-output>
  <resultStatus>OK</resultStatus>
  <paperMetadata>
    <submitDateTime>2002-02-02T14:10:02Z</submitDateTime>
    <publicId>astro-ph/0702600</publicId>
    <latestPaperURL format="PDF">http://arxiv.org/pdf/astro-ph/0702600</latestPaperURL>
    <latestPaperURL format="PS">http://arxiv.org/ps/astro-ph/0702600</latestPaperURL>
    <latestPaperURL format="repository-summary-page">http://arxiv.org/abs/astro-ph/0702600</latestPaperURL>
    <version number="1" status="public">
      <dateTime>2007-02-22T14:10:02Z</dateTime>
      <title>The 21cm angular-power spectrum from the dark ages</title>
      <abstract><latex>At redshifts $z \agt 30$ neutral hydrogen...</latex></abstract>
       <submitter type="author-person" repositoryAuthorID="bcadf518">
         <name>Antony Lewis</name>
         <affiliation>IoA, Cambridge</affiliation>
         <contactPage>http://cosmologist.info/</contactPage>
         <repositoryIndexPage>http://arxiv.org/find/astro-ph/1/au:+Lewis_A/0/1/0/all/0/1</repositoryIndexPage>
       </submitter>
       <author type="author-person" repositoryAuthorID="bcadf518">
         <name>Antony Lewis</name>
         <affiliation>IoA, Cambridge</affiliation>
         <contactPage>http://cosmologist.info/</contactPage>
         <repositoryIndexPage>http://arxiv.org/find/astro-ph/1/au:+Lewis_A/0/1/0/all/0/1</repositoryIndexPage>
      </author>
      <author type="author-person">
         <name>Anthony Challinor</name>
         <affiliation>IoA, Cambridge</affiliation>
         <affiliation>DAMTP, Cambridge</affiliation>
         <repositoryIndexPage>http://arxiv.org/find/astro-ph/1/au:+Challinor_A/0/1/0/all/0/1</repositoryIndexPage>
      </author>
      <comments>29 pages..</comments>
      <paperURL format="PDF">http://arxiv.org/pdf/astro-ph/0702600v1</paperURL>
      <paperURL format="PS">http://arxiv.org/ps/astro-ph/0702600v1</paperURL>
      <paperURL format="repository-summary-page">http://arxiv.org/abs/astro-ph/0702600v1</paperURL>
      <keyword>21cm</keyword>
      <keyword>dark ages</keyword>
      <keyword>CMB</keyword>
      <keyword>power spectrum</keyword>
      <category>astro-ph</category>
    </version>
  </paperMetadata>
</rioja-repository-output>

See the fully qualified sample XML output file.

RIOJA R-O1: Journal status change notification

The purpose of this optional API is for the journal to inform the repository of changes in the status of the paper within the journal submission process. If implemented, the repository is automatically informed via this API when the journal submission status changes. To ensure the notification is genuine the repository should call the journal getStatus API, which can also be used to obtain more information.

setStatus optional repository API

Input: journalId (string), repository paperId (string) and paperVersion (positiveInteger), and paperStatus (submit-status-enum) describing paper status in journal submission process. e.g.
```
 http://someurl.com/rioja?apiName=setStatus&paperId=1234.5678&paperVersion=1&journalID=OJAC&paperStatus=submitted
```
paperStatus can be one of accepted, published, rejected or withdrawn.

Output: resultStatus. e.g.

<rioja-repository-output>
  <resultStatus>OK</resultStatus>
</rioja-repository-output>

RIOJA R-O2: Get journal status from repository

Since a repository may host papers on various different journals, this optional API allows a journal to obtain the status of a paper in other journals, for example to prevent submission to more than one journal.

getStatus optional repository API

Input: repository paperId e.g.

 http://someurl.com/rioja?apiName=getStatus&paperId=1234.5678

Output: allJournalStatus with list of journalID and status of the latest repository paperVersionID within that journal. Usually only one, but may be re-submitted to another journal after rejection. e.g.

<rioja-repository-output>
  <resultStatus>OK</resultStatus>
  <allJournalStatus>
    <journalID>OJAC</journalID>
    <paperVersion>2</paperVersion>
    <status>submitted</status>
  </allJournalStatus>
</rioja-repository-output>

RIOJA R-O3: Get repository trackbacks

This optional repository API allows journals to get information about trackback links to versions of a paper on the repository. The list of trackbacks can be empty.

getTrackbacks optional repository API

Input: repository paperId. e.g.

 http://someurl.com/rioja?apiName=getTrackbacks&paperId=0705.3980

Output: list of trackback information

<rioja-repository-output>
  <resultStatus>OK</resultStatus>
  <trackback>
    <name>CosmoCoffee</name>
    <URI>http://cosmocoffee.info/viewtopic.php?t=891</URI>
    <dateTime>2007-05-29T00:00:00Z</dateTime>
    <paperVersion>1</paperVersion>
  </trackback>
  <trackback>
     ...
  </trackback>
</rioja-repository-output>

RIOJA R-O4: Get repository statistics

This optional repository API allows journals to get information about paper download statistics from the repository.

getStatistics optional repository API

Input: repository paperId

 http://someurl.com/rioja?apiName=getStatistics&paperId=1234.5678

Output: statistics e.g.

<rioja-repository-output>
  <resultStatus>OK</resultStatus>
  <statistics>
    <downloads-week>32</downloads-week>
    <downloads-month>123</downloads-month>
    <downloads-year>343</downloads-year>
    <downloads-total>363</downloads-total>
  </statistics>
</rioja-repository-output>

Get current paper information

This is a wrapper API to return the results of getStatus, getTrackbacks and getStatistics all in one go.

getCurrentPaperInfo optional repository API

Input: repository paperId

 http://someurl.com/rioja?apiName=getCurrentPaperInfo&paperId=1234.5678

Output: statistics, trackback list, journalStatus.

getJournalInfo: Get journal information

Input: journalId, e.g.

 http://someurl.com/rioja?apiName=getJournalInfo&jounalId=OJAC

Output: journalInfo structure with information about the journal. e.g.

<rioja-journal-output>
  <resultStatus>OK</resultStatus>
  <journalInfo>
    <journalID>OJAC</journalID>
    <journalName>Open Journal of Astrophysics and Cosmology</journalName>
    <ISSN>1234-5678</ISSN>
    <OAIurl>http://arxivjournal.org/sample/oai2.php</OAIurl>
    <supportedAPI>getJournalInfo</supportedAPI>
    <supportedAPI>getStatus</supportedAPI>
    <supportedAPI>submit</supportedAPI>
    <APIVersion>1.0</APIVersion>
    <homepage>http://cosmologist.info/ojs-2.0/index.php/astrocosm</homepage>
    <submitPage>http://cosmologist.info/ojs-2.0/index.php/astrocosm/user/register</submitPage>
  </journalInfo>
</rioja-journal-output>

RIOJA-J1: get journal status

This API returns the status of a given repository paper within the journal.

getStatus Required journal API

Input: repositoryId and repository paperId. e.g.

 http://someurl.com/rioja?apiName=getStatus&repositoryId=arXiv.org&paperId=1234.5678

Output: journalStatus structure with status in the journal

<rioja-journal-output>
  <resultStatus>OK</resultStatus>
  <journalStatus>
     <journalPaperId>1234</journalPaperId>
     <journalReference>OJAC 1234.2345 (2008)</journalReference>
     <journalPaperURL>http://cosmologist.info/ojs-2.0/index.php/astrocosm/article/view/1</journalPaperURL>
     <repositoryPaperVersion>2</repositoryPaperVersion>
     <submitDate>2007-02-02T14:10:02Z</submitDate>
     <status>submitted</status>
     <submitDetail>withEditor</submitDetail>
   </journalStatus>
</rioja-journal-output>

Note that normally journalReference and journalPaperURL would not normally be provided unless status is published. Further information about published version can be obtained from journal OAI interface.

RIOJA-JO1: submit from repository

This optional API allows the repository to re-direct to a page on the journal website immediately after repository submission. The API takes the repository paper details and outputs a re-direct page to continue the submission process. Typically the repository would display a list of supported journals after confirming paper submission, and provide Submit button that would call this API and then re-direct to the journal website.

submit Optional journal API

Input: repositoryId, repository paperId, optional (set of) email associated with the paper. e.g.

 http://someurl.com/rioja?apiName=submit&repositoryId=arXiv.org&paperId=1234.5678&email=email_1

Output: submissionURL to re-direct to. e.g.

<rioja-journal-output>
  <resultStatus>OK</resultStatus>
  <submissionURL>http://arxivjournal.org/submit.php?author=id-of-email_1&rep=arXiv&paper=1234.2345</submissionURL>
</rioja-journal-output>

FAQ

Why not just use OAI?

Several reasons.
1. OAI is designed for metadata harvesting not as an immediate-reponse API to be used interactively. For RIOJA journals need to be able to get metadata dynamically during the submission process; OAI allows "wait" responses which require re-querying at a later time.
2. RIOJA allows for extraction of information before a paper is public on a repository (e.g. for integrated submission) before it would be available by OAI
3. RIOJA needs to track paper versions carefully. OAI does not include detailed paper version information.
4. There should be a well-defined format for titles and abstracts with text formatting and equations so that they can display the same way on the journal and repository without further editing; OAI is very flexible but very vague.
5. RIOJA requires serveral other functions apart from extracting Metadata

Open issues

The APIs currently assume author-managed papers, i.e. that the author receives back any copy-edited version of the paper and re-submits to the repository himself. This could be automated, or there could be an API to allow the journal to modify the version of the paper on the repository.

Specifications for unambiguous formatting in paper titles and abstracts. See SimpleTex.html for suggested tex-enabled format. Crossref also allows a mixed-format XML with bold, italic support - this could be added though types not importable(?).
What generic types can be used for author/paper information? Crossref specification seems to have best detail of author/contributors, but types are not importable. Dublin Core is very vague. Why is there no library standard? Why is there no standard to track authors by unique IDs (like DOI for authors)?

Antony Lewis 2007.