The RQC API for manuscript handling systems

last change: 2021-05-20

This is a work-in-progress and not yet ready for use!

On this page:

Elsewhere:

1. 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).

2. API for manuscript handling systems (MHS)

2.1 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 provide a review) 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 assign the case to a subjournal, grade reviews A, B, C, and set notification parameters for the other participants (authors, reviewers, other editors).
  11. RQC redirects the Editor's browser back to the MHS.
  12. The Editor either makes an acceptance decision or first 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. RQC initiates the grading process in case the editor has skipped steps 6 to 11.

2.2 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 POST 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. Review text supplied in the initial PUT can be modified by the later call.

GET is supported for checking the validity of a pair of journal ID and journal key. Other than that, GET is supported solely for testing purposes; it is not needed for normal operation.

DELETE is not supported because RQC attempts to never remove gradings.

2.3 URL structure

All URLs have the following form: https://reviewqualitycollector.org/j/mhsapi/gp/<journal_id>/<submission_url_id>/<token> where

2.4 Requirements for the MHS database schema

2.4.1 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.

2.4.2 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 might also require an extension of the MHS GUI to set those values.

Further fields
will have to be added to the journal transaction data in the MHS; they describe which reviewers have opted in to or opted out of participating in RQC for this year for this journal:

2.5 Requirements for MHS functionality

2.5.1 One-time preparation step: Registration

The MHS must allow editors to enter the journal_id and journal_key they received from their publisher for the given journal, and the MHS must validate these data upon entry by issuing a HEAD call as described below (and get a '200 OK' HTTP response status). Invalid data must not be accepted and must never be used for RQC calls.

2.5.2 Potential per-review step: Reviewer opts in/out

The dialog by which a reviewer submits a review must be extended: If there is no entry yet for this reviewer, journal, and year in the table described in Section 2.4.2 above, the MHS must ask the reviewer if they want to opt into participating in RQC for this journal for this year or want to opt out of participating in RQC for this journal for this year.

Use the following wording for the question:

I want to participate in Review Quality Collector (RQC) for all my reviews for this journal this year. My reviewing data will be submitted to RQC and RQC will provide me with a reviewing receipt in exchange. I understand the purpose of RQC and its use of my data as described at https://reviewqualitycollector.org/t/terms-and-privacy. I can make a separate decision on this for other journals. I can make a separate decision on this for the present journal next year.

Yes / No

Answering yes creates a contract between the reviewer and RQC where the reviewer provides a review and RQC provides a reviewing receipt. This contract is the basis on which RQC is allowed (by privacy regulations such as the EU-GDPR) to process the reviewer's data. Different wording would provide a shakier basis and should not be used.

After the reviewer has answered the above dialog, create an entry for it and do not ask this reviewer again for reviews pertaining to the same year and journal.

Which year? "This year" in the above text does not always mean the year in which the statement is made; it can sometimes refer to the previous year. "This year" means the calendar year in which the first review for the present submission was received. (This is needed because RQC needs to handle all reviews for the same submission as one unit.)

(Don't worry: This was the most complicated aspect of what the MHS needs to do.)

2.5.3 Per-submission steps: Submit to RQC

2.6 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.

2.7 Check token

2.7.1 Introduction

A GET 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 so the corresponding reviews would never reach RQC evaluation.

2.7.2 URL

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

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

2.7.3 RQC response: status codes and body

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

2.8 POST

2.8.1 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, because the behavior of RQC may depend on the decision.

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 the first of the calls in the queue submitted again. If a call succeeds, remove it from the queue. If it fails, count the failure, move the call to the end of the queue, and retry the next call on the queue 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.

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

2.8.2 content-type

An API call must have a Content-Type: application/json HTTP header and provide its data as UTF-8-encoded JSON in the body. See json.org or JSON at Wikipedia.

2.8.3 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 POST
    "mhs_software": "Open Journal Systems 3.5.1"
    "mhs_adapter_version": "RQC plugin 1.1.17"
    "interactive_user": "myeditor@anywhwere.org"
    "mhs_submissionpage": "https://mymhs.example.com/journal17/user29?submission=submission31"
    "title": "Rather Altogether Modestly Long-ish Submission Title 21",
    "visible_id": "MANU-10021/R2",
    "submitted": "2022-02-01T11:07:42Z",
    "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      
        },
        {
            "email": "editor3@sm.wh",
            "firstname": "Kim",
            "lastname": "Kong",
            "orcid_id": "0000-0001-5592-0007"
            "level": 3      
        }
    ],
    "review_set": [
        {
            "visible_id": "0",
            "invited": "2022-02-08T14:30:10Z",
            "agreed": "2022-02-09T07:22:03Z",
            "expected": "2022-02-28T14:30:10Z",
            "submitted": "2022-02-15T09:09:46Z",
            "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": "2022-02-15T00:00:00Z",
            "agreed": "",
            "expected": "2022-02-28T00:00:00Z",
            "submitted": "2022-03-01T00:00:00Z",
            "text": "This is the text of review 2.\It is multiple lines long, some of which are themselves a bit longer (like this one, for instance; at least somewhat -- truly long would be longer, of course)\n\nLine 4, the last one.",
            "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.)

2.8.4 Size limits

Cut off longer values at the end for the POST request, or the request will fail.

2.8.5 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. Possibly an Excel upload is a suitable compromise between easy-to-build and easy-to-use.)

2.8.6 RQC response: status codes and body

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

2.8.7 Semantics of subsequent POST calls

Once a submission has been POSTed to RQC, it can be updated by additional calls only in the following respects:

2.8.8 Discussion of consequences

2.9 GET

TO DO.!!!

3. 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.

4. Testing your MHS/RQC adapter

5. API change history



Sun 2021-10-24 16:08 UTC

Review Quality Collector  © 2012-2021

Contact/Imprint/Impressum