In addition there are optional APIs allowing the journal to display trackback and download statistics for the paper.
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:
http://someurl.com/rioja?apiName=getRepositoryInfo
<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>
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
http://someurl.com/rioja?apiName=validateAuthor&paperId=1234.5678&email=email_1,email_2,email_3
<rioja-repository-output> <resultStatus>OK</resultStatus> <validEmail>email_1</validEmail> <validEmail>email_2</validEmail> </rioja-repository-output>
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
http://someurl.com/rioja?apiName=getMetadata&paperId=astro-ph/0702600
See the fully qualified sample XML output file.<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>
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
paperStatus can be one of accepted, published, rejected or withdrawn.http://someurl.com/rioja?apiName=setStatus&paperId=1234.5678&paperVersion=1&journalID=OJAC&paperStatus=submitted
<rioja-repository-output> <resultStatus>OK</resultStatus> </rioja-repository-output>
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 APIhttp://someurl.com/rioja?apiName=getStatus&paperId=1234.5678
<rioja-repository-output> <resultStatus>OK</resultStatus> <allJournalStatus> <journalID>OJAC</journalID> <paperVersion>2</paperVersion> <status>submitted</status> </allJournalStatus> </rioja-repository-output>
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
http://someurl.com/rioja?apiName=getTrackbacks&paperId=0705.3980
<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>
This optional repository API allows journals to get information about paper download statistics from the repository.
getStatistics optional repository API
http://someurl.com/rioja?apiName=getStatistics&paperId=1234.5678
<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>
This is a wrapper API to return the results of getStatus, getTrackbacks and getStatistics all in one go.
getCurrentPaperInfo optional repository API
http://someurl.com/rioja?apiName=getCurrentPaperInfo&paperId=1234.5678
http://someurl.com/rioja?apiName=getJournalInfo&jounalId=OJAC
<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>
This API returns the status of a given repository paper within the journal.
getStatus Required journal API
http://someurl.com/rioja?apiName=getStatus&repositoryId=arXiv.org&paperId=1234.5678
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-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>
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
http://someurl.com/rioja?apiName=submit&repositoryId=arXiv.org&paperId=1234.5678&email=email_1
<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>
Why not just use OAI?
Several reasons.