Chapter 5. RESTful API for all Users, Raters and Moderaters

The following describes the API calls and functionality implemented. The examples below are all run from a DICE machine and use some support tools to get and manage credentials. As long as you have a valid (unexpired) authentication cookie you can run these calls from anywhere using whatever tools are appropriate.

All the operations that can be done via the web browser interface can also be done via the API. The access levels and what is read only etc are all identical.

authGET https://gw.referee.inf.ed.ac.uk/api/v1/my_papers
{
    "my_papers": [
        {
            "abstract": "Quite amazing stuff worth a Nobel",
            "double_weight": true,
            "id": 3,
            "pure_url": "news.bbc.co.uk",
            "rank": "2nd",
            "reason": "unbeatable stuff",
            "title": "Test Paper 2",
            "uri": "/api/v1/my_papers/3"
        },
        {
            "abstract": "Tim wrote this first",
            "double_weight": false,
            "id": 4,
            "pure_url": "www.google.com",
            "rank": "3rd",
            "reason": "its soooo good",
            "title": "Test Paper 1",
            "uri": "/api/v1/my_papers/4"
        },
        {
            "abstract": "Who would have though it but we prove",
            "double_weight": false,
            "id": 5,
            "pure_url": "www.ed.ac.uk",
            "rank": "1st",
            "reason": "astounding what more can I say",
            "title": "Test Paper 3",
            "uri": "/api/v1/my_papers/5"
        }
    ]
}

Above obtains authentication and returns all papers I have submitted (just using test data in the example above). This is normally however just a copy of the data that has been fed in from PURE. If you have not submitted any papers this will return an empty array. Nothing can be updated via this call (you will get an entirely unhelpful error).

You can use some simple command line tools to convert the above, or any of the JSON output from these API calls, to CSV (to load into Excel or Libreoffice for example):

authGET https://gw.referee.inf.ed.ac.uk/api/v1/my_papers | \
  jq -r '.my_papers[] | [.id, .rank, .pure_url, .title, .reason, .abstract, .double_weight | tostring] | @csv'
"3","2nd","news.bbc.co.uk","Test Paper 2","unbeatable stuff","Quite amazing stuff worth a Nobel","true"
"4","3rd","www.google.com","Test Paper 1","its soooo good","Tim wrote this first","false"
"5","1st","www.ed.ac.uk","Test Paper 3","astounding what more can I say","Who would have though it but we prove","false"

Since the JSON output will always use the UTF-8 character encoding, so some characters may not be correctly shown using tools like authGET or curl. One way to fix this is to use jq. as above, for example:

authGET https://gw.referee.inf.ed.ac.uk/api/v1/my_papers
{
    "my_papers": [
        {
            "abstract": "wibble \u201cmilestone paper\u201d wibble blah.",
            "double_weight": false,
            "id": 88,
            "pure_url": "https://no.where.com/",
            "rank": "1st",
            "reason": null,
            "title": "Blah de Blah",
            "uri": "/api/v1/papers/88"
        }
    ]
}
authGET https://gw.referee.inf.ed.ac.uk/api/v1/my_papers | jq
{
  "my_papers": [
    {
      "abstract": "wibble “milestone paper” wibble blah.",
      "double_weight": false,
      "id": 88,
      "pure_url": "https://no.where.com/",
      "rank": "1st",
      "reason": null,
      "title": "Blah de Blah",
      "uri": "/api/v1/papers/88"
    }
  ]
}

This:

authGET https://gw.referee.inf.ed.ac.uk/api/v1/my_papers2rate

returns the list of papers I have to rate, e.g. abbreviated output of some test data:

authGET https://gw.referee.inf.ed.ac.uk/api/v1/my_papers2rate
...
     {
         "abstract": "Incontrovertible Evidence the Earth is Flat",
         "comment": null,
         "double_weight": false,
         "firstname": "Joe",
         "id": 14,
         "lastname": "Bloggs",
         "paper_id": 7,
         "pure_url": "www.the-earth-sure-is-flat.com",
         "rank": "1st",
         "rating": null,
         "reason": "sheer brilliance",
         "title": "Yes, The Earth IS Flat",
         "uri": "/api/v1/my_papers2rate/14"
     },
...

The same call can be used to update both the rating and the comment for that rating. To do this it is easiest to first save the authentication cookie:

export COSIGN_COOKIEFILE=~/.cookies.txt
rm -f $COSIGN_COOKIEFILE
touch $COSIGN_COOKIEFILE
chmod 0700 $COSIGN_COOKIEFILE
authGET https://gw.referee.inf.ed.ac.uk/api/v1/my_papers2rate
export SESSION_COOKIE=`awk '/cosign-gw/{print$5"="$6}' $COSIGN_COOKIEFILE`

Now I can make the update:

curl -X PUT --cookie "$SESSION_COOKIE" \
"https://gw.referee.inf.ed.ac.uk/api/v1/my_papers2rate/14?rating=2*&comment=changed"
{
 "my_papers2rate": {
     "abstract": "Incontrovertible Evidence the Earth is Flat",
     "comment": "changed",
     "double_weight": false,
     "firstname": "Joe",
     "id": 14,
     "lastname": "Bloggs",
     "paper_id": 7,
     "pure_url": "www.the-earth-sure-is-flat.com",
     "rank": "1st",
     "rating": "2*",
     "reason": "sheer brilliance",
     "title": "Yes, The Earth IS Flat",
     "uri": "/api/v1/my_papers2rate/14"
 }
}

You will need to ensure any parameter values are correctly encoded to URI specification.

This one works identically to above:

authGET https://gw.referee.inf.ed.ac.uk/api/v1/my_papers2moderate

but lists the papers I have to moderate and can be used exactly as above to set the moderated rating and comment for that paper.