Researchfish API Reference Guide
Researchfish Award and Outcome API
The Researchfish API is designed for eVal users to export or download outputs from the Researchfish online platform. This enables API users to map information contained within Researchfish to a third party system such as a grant management system, using the Award reference number.
This document contains details on how to use the API and a worked example, together with some specific examples using the CURL utility.
Researchfish is not responsible for any integration code written by third parties for use with third party systems and email-only support is provided by Researchfish. Use of this API is not covered by the Standard Terms and Conditions.
Format
The Award and OutcomeAPIs are availableover a REST interface, with resultsavailable in both XML and JSON formats.
Authentication
Access to the APIs is access controlled and the ‘user’ must authenticate first. Authentication is performed using a username and password. Only users that have the API Role set in the Admin interface can use the API:
The endpoint for the login API is:
https://api.researchfish.com/restapi/user/login
The username and password must be posted in the following format:
"username":"yourusername", "password":"yourpassword"}
The login API will set a cookie which may be used for further API requests. The cookie value is also returned in the response for developers who prefer to handle the session manually.
Response Formats
Results are available in both XML and JSON formats. To choose JSON use the endpoint:
/rest api
to choose XML use the endpoint:
/xml api
Response Paging
Up to 25 resultswill be returnedwith each request.
If further pages of results are available, the “next” parameter will be returnedwith the page number of thenext result set. To request subsequent pages, the start parameter must be supplied:
&start=1
The first page of results is page 0.
Use of the Awards API
The AwardsAPI returns the list of awards visible to the account in use. Request syntax:
https://api.researchfish.com/restapi/award?
Optional Parameters:
&funder=[funder code]
Use of Outcomes API
The Outcomes API returns the list of outcomes attributed to the awards visible to the account in use.
Request syntax:
https://api.researchfish.com/restapi/outcome?
Optional Parameters:
§ion=[section name]&agreement=[award/agreement_id]
Examples
Testing the API with Postman (REST client add-on for Chrome):
Logging In
Fetching a list of Awards
Fetching a list of outcomes (publications)
Fetching a list of outcome (publications) XML format
API Response Data
Awards
The following fields will be returned when calling a Awards API:
• id
• agr_id (alias of id)
• location
• pi
• pi_title
• pi_initials
• pi_surname
• pi_email
• fa_reference
• fa_name
• funding_organisation
• location
• researchorg_id
• funding_start_date
• funding_end_date
• funding_value
• funding_currency
• award_abstract
• award_summary
• response_code
Outputs/Outcomes
For details on the possible response data for output/outcome types please register for free access to the common question set, which can be found at
https://app.researchfish.com/questions
Curl Examples
The CURL utility can be used to send HTTP requests from the command line and is available for a number of operating systems.
To download the version for your system please visit:
Logging In
> curl i —H "Content-Type: application/json" -X POST -d ‘{"username":"X","password":"X"}’
https://api.researchfish.com/restapi/user/login
Response:
HTTP/1.1 200 OK
Cache-Control: no-cache,must-revalidate, post-check=0,pre-check=0
Content-Type:application/json Date: Fri, 06 Nov 2015 10:28:22 GMT
ETag: "1446805702"
Expires: Sun, 19 Nov 1978 05:00:00 GMT
Last-Modified: Fri, 06 Nov 2015 10:28:22+0000 Server: Apache
Set-Cookie:SSESSe05afc1b5183a378f29b3fd64d27f590=QyZZixzZsftvLx7YRzq ZseLevmr5aa9b1k-lHlsLwE; path=/;domain=.researchfish.com; secure; HttpOnly
Vary: Accept
Content-Length:1637 Connection: keep-alive
{ "sessid":"QyZZixzZsftvLx7YRzqZseLevmr5a-a9b1k-lHlsLwE","session_name":"SSESSe05afc1b5183a378f29b3fd64d27f590","token":"m38C3RfXVB0cw1So39lmX5PuOlfTipJdk24079czgfk", "user":{"uid":"12349",
"name":"giles",
"mail":"giles@x43.com",
"theme":"",
"signature":"","signature_format":"plain_text","created":"1328298890","access":"1446805344","login":"1446805702",
"status":"1","timezone":"Europe/London","language":"",
"picture":"0",
"data":{ "contact":"1","ckeditor_default":"t","ckeditor_show_toggle":"t","ckeditor_width":"100 %",
"ckeditor_lang":"en","ckeditor_auto_lang":"t", "mimemail_textonly": 0},
"uuid":"ec84d764-8c51-0de4-5509-ef28a5c02420","roles": {"2":"authenticated user",
"7":"RCAFull Access", "29":"RCAAPI Access"},
"field_groups":[],"field_title": ... etc
}
}
The cookie set by this request should be made with all future authenticated requests.
Request Awards
curl --cookie "SSESSe05afc1b5183a378f29b3fd64d27f590=QyZZixzZsftvLx7YRzqZseLevmr5aa9b1k-lHlsLwE"-X GET
https://api.researchfish.com/restapi/award
Response
{"count":25,"next":1,"results":[{"id":"...
Logout
curl --cookie "SSESSe05afc1b5183a378f29b3fd64d27f590=QyZZixzZsftvvmr5a-a9b1k-lHlsLwE" -X GET https://api.researchfish.com/user/logout
Document History
Version |
Author |
Change Summary |
Document Date |
|
1.0 |
Giles Mitton |
Initial Draft |
15-03-15 |
|
1.1 |
Sean Newell |
Added reference to user authentication |
21-04-15 |
|
1.2 |
Sean Newell |
Added clarification based on user feedback |
10-09-15 |
|
1.3 |
Giles Mitton |
Minor corrections plus same CURL scripts added |
05-02-17 |
|
1.4 |
Ross Pullar |
Branding and company detail updates |
21-10-21 |