RIOJA Journal-Repository APIs

Draft version 1, August 2007. Notes and history.


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

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:

getRepositoryInfo: Get repository information

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

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

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

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

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

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

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

getJournalInfo: Get journal information

RIOJA-J1: get journal status

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

getStatus Required journal API

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


Open issues

Antony Lewis 2007.