The RQC API for manuscript handling systems

last change: 2018-11-19

On this page:

What is an API and why is it needed?

For RQC to be practical, it needs to be integrated with the manuscript handling system (MHS) to which the reviews are submitted.

For conferences, RQC can play the active part: All reviews are present at a particular time (the reviewing deadline, or shortly later) and RQC can go and get all the submission, reviewer, and reviewing data from the manuscript handling system (after the PC chairs have permitted it to do so) and then do its job with them.

For journals, this mode of operation does not work: Reviews trickle in all the time and it makes no sense to wait with grading them until, say, the end of the year. So the manuscript handling system needs to actively transmit the data for reviews to RQC as they come in. RQC needs to provide a technical way to do that: The API (application programming interface).

API for manuscript handling systems (MHS)

Main use case

Overall, the process for handling one submission to journal X works roughly as follows:

Actors: The journal's manuscript handling system (MHS), Editor, Review Quality Collector system (RQC), Reviewers

  1. The MHS receives a submission S.
  2. The Editor invites Reviewers A, B, C to review S.
  3. The MHS receives review A.
  4. The MHS receives review B.
  5. The MHS receives review C or the Editor becomes impatient to wait for it and wants to make a decision on S.
  6. The Editor triggers "Initiate RQC review grading" for S in the MHS.
  7. The MHS submits data about submission S, and reviews A, B, and (if the reviewer had agreed to make it) C to RQC via the API.
  8. RQC replies with a URL G (of the RQC grading page for S).
  9. The MHS redirects the Editor's browser to page G.
  10. The Editor uses RQC page G to grade reviews A, B, C.
  11. RQC redirects the Editor's browser back to the MHS. (At this point, RQC may also involve (via Email) authors, reviewers, and other editors in the grading as needed according to the RQC configuration for jounal X.)
  12. The Editor either makes an acceptance decision or involves other editors and the decision is then made in some later session.
  13. The MHS submits data about the decision for submission S to RQC.
  14. If the Editor had not used "Grade reviews" before, RQC will initiate the grading process via email at this point.

API overview

So far, the RQC API has only one single endpoint. The URLs to reach it are described in a separate section below. The endpoint is normally used twice for each submission, both times using the PUT HTTP verb: First to deposit the submission, editors, and reviewing data. Later to add information about the editorial decision (and possibly any additional reviews that may have arrived in the meantime). Data supplied in the initial PUT will not be modified by later calls.

HEAD is supported for checking the validity of a pair of journal ID and journal key.

GET is supported solely for testing purposes; it is not needed for normal operation. (TODO: Report grading summary information in the GET response so the MHS can show grading status information.)

DELETE is not supported because review grading is initiated once reviews are received by RQC and RQC will not remove gradings.

URL structure

All URLs have the following form: https://reviewqualitycollector.org/j/mhsapi/<journal_id>/<submission_id>/?token=<token> where

Requirements for the MHS database schema

What you probably have already

RQC requires the following data for each submission (which thus needs to be stored in the MHS database somewhere):

(These are not the actual names used by RQC, see further down.)

For some of these, reasonable defaults are available; in particular, firstname can be left empty if unavailable and the full name supplied in the lastname field; if ORCID IDs are not known, that field can be left empty. Other fields are very important; in particular, RQC uses email addresses as keys for identifying people, so if several authors share an email address, there is trouble and only one of them can be reported to RQC.
This is described in more detail in the request descriptions below.

What you need to add

Two fields will have to be added to each journal's master data in the MHS:

Beyond that, it may be needed to store an extra mapping of the codes for editorial decisions; see under decision below. This would also require an extension of the MHS GUI to set those values.

Requirements for MHS functionality

Authentication token

Authentication is performed via the token submitted in the URL with each call. A different token must be supplied for each combination of journal ID and submission ID as follows:

The token is required for all calls. If it is wrong (and only then), the response will have HTTP status code 401 Unauthorized. This fact will not be repeated in the response code listings below.

Introduction

A HEAD request must be used by the MHS to make sure a pair of journal_id and journal_key is indeed valid. This is useful for validating the data input by an editor in a journal configuration form, because if journal_id or journal_key are wrong, none of the later RQC calls would succeed and the corresponding reviews would never reach RQC evaluation.

URL

For this purpose, the URL is formed differently, as follows: https://reviewqualitycollector.org/j/mhsapi/<journal_id>/<datetime>/?token=<token> where

The purpose of submitting current time in the URL is to make sure the clocks of MHS and RQC are properly aligned.

RQC response: status codes

RQC will respond to such a HEAD request with one of the following status codes:

PUT

Explicit vs. implicit vs. delayed calls

Explicit calls: The MHS should provide a button or link "RQC-grade reviews" on the editors' submission administration page as soon as at least one review has been received. The editor can use this GUI element to submit the currently existing reviews for this submission to RQC, will be immediately redirected to RQC for grading these reviews, and then be redirected back to the MHS. Using this functionality is called an "explicit call". Explicit calls are optional: Grading the review is a nice preparatory step for making the editorial decision, but it is not necessary to perform the grading at this point -- and possibly this particular editor is not involved in the grading at all. More than one editor may make an explicit call.

Implicit calls: Whenever an editorial decision for a submission is made (or changed) in the MHS, the MHS must make an "implicit call" to RQC and submit the review data. The MHS may or may not redirect the user to RQC at this point as it sees fit. Implicit calls are mandatory, they must be made for each submission each time a new editorial decision is stored.

Delayed calls: A call to RQC may fail due to network problems or unavailability of the RQC service. If that happens, the call should be put into a backlog of calls to retry. This backlog should be revisited once per day and each of the calls in the queue submitted again. If a call succeeds, remove it from the queue. If it fails, count the failure and retry the next day. Delete calls after 10 failures. If any call fails on a given day, stop all retrying for that day in order to avoid useless calls.
Note that this behavior applies only to unavailability failures; it should not be applied if the authentication token is wrong or no configuration has deposited in RQC for a given submission type.

See the response status codes below for a discussion of the redirection mechanism and the discussion of consequences for design considerations.

content-type

The calls must have a Content-Type: application/json HTTP header and provide their data as UTF-8-encoded JSON in the body. See json.org or JSON at Wikipedia. (If you absolutely need to provide your data as XML, speak up; I may be willing to support it.)

Example JSON body

Here is an example what that JSON may look like; an explanation of each field follows below:

{
    "api_version": "1.0alpha",  // GET only, not needed in PUT
    "interactive_user": "myeditor@anywhwere.org"
    "mhs_redirect_url": "https://mymhs.example.com/journal17/user29?submission=submission31"  // PUT only, not present in GET
    "title": "Rather Altogether Modestly Long-ish Submission Title 21",
    "visible_id": "MANU-10021/R2",
    "submitted": "2017-02-01T00:00:00Z",
    "predecessor_submission_id": "MANU-10021-R1",
    "predecessor_visible_id": "MANU-10021/R1",
    "author_set": [
        {
            "email": "author31@sm.wh",
            "firstname": "A.N.",
            "lastname": "Author",
            "orcid_id": "0000-0001-5592-0005"
            "is_corresponding": true,
            "order_number": 1
        },
        {
            "email": "other_author@sm.wh",
            "firstname": "Brubobolob",
            "lastname": "Authoress",
            "orcid_id": "0000-0001-5592-0006"
            "is_corresponding": true,
            "order_number": 2
        }
    ],
    "editorassignment_set": [
        {
            "email": "editor1@sm.wh",
            "firstname": "Keen",
            "lastname": "Editorus",
            "orcid_id": "0000-0001-5592-0003"
            "level": 1                
        },
        {
            "email": "editor2@sm.wh",
            "firstname": "Keener",
            "lastname": "Editora",
            "orcid_id": "0000-0001-5592-0004"
            "level": 3      
        }
    ],
    "review_set": [
        {
            "visible_id": "0",
            "invited": "2017-02-08T00:00:00Z",
            "agreed": "2017-02-09T00:00:00Z",
            "expected": "2017-02-28T00:00:00Z",
            "submitted": "2017-02-15T00:00:00Z",
            "text": "This is the text of review 1.",
            "is_html": false,
            "suggested_decision": "minorrevision",
            "reviewer": {
                "email": "reviewer1@sm.wh",
                "firstname": "J.",
                "lastname": "Reviewer 1",
                "orcid_id": "0000-0001-5592-0001"
            }
        },
        {
            "visible_id": "1",
            "invited": "2017-02-15T00:00:00Z",
            "agreed": "2017-02-15T00:10:00Z",
            "expected": "2017-02-28T00:00:00Z",
            "submitted": "2017-03-01T00:00:00Z",
            "text": "This is the text of review 2.",
            "is_html": false,
            "suggested_decision": "accept",
            "reviewer": {
                "email": "reviewer2@sm.wh",
                "firstname": "J.",
                "lastname": "Reviewer 2",
                "orcid_id": "0000-0001-5592-0002"
            }
        }
    ]
    "decision": "accept",
}

(Please make sure you correctly discriminate integer literals from corresponding strings (1 vs "1") and the three special JSON literals true, false, and null from their unrelated string look-alikes "true", "false", and "null". null is never used in the RQC API.)

Semantics

The field ordering is not relevant.

This is what each field means and how to use it:

If a journal uses a different set of decision types, match those to their closest equivalent in the above set.
If an MHS allows each journal to define an arbitrary list of decision codes and the MHS cannot know their meaning, the RQC adapter for that MHS must allow the editors to define a mapping from the journal's internal codes to the above codes for RQC. (Not fun, sure, but there is no way around it.)

RQC response: status codes

TO DO.

Discussion of consequences

GET

TO DO.

RQC API implementation status

The RQC functionality for journals and hence the API are not yet implemented. Implementation is under way.

Until both the RQC-side API implementation and the first MHS adapter using the API are finished, the API is considered provisional and is subject to sudden change.

If you want to start implementing the API for your manuscript handling system now, please contact Lutz Prechelt.

Testing your MHS/RQC adapter

TO DO.

Eventually, RQC will support test journals that do not show up in official journal lists and from which reviews will automatically be deleted after some time.



Mon 2018-12-10 00:28 UTC

Review Quality Collector  © 2012-2018

Imprint / Impressum