Important changes to the SHERPA/RoMEO Application Programmers' Interface
The following important changes will be made to the SHERPA/RoMEO Application Programmers' Interface (API) during autumn 2013:
- API version 2.4 will be closed down.
- Heavy users of the API will be required to use access keys.
- The legacy output schema for article versions (pre-print and post-print only) will be dropped.
SHERPA/RoMEO is planning to close down the old version V.2.4 of the API by the 25th November 2013, with certain restrictions being introduced before then. V.2.4 API users will need to upgrade their applications to use the current version V.2.9. This is explained later.
With immediate effect, we are limiting the number of requests unregistered users can make to API V.2.4 each day. The limit has initially been set very high (500,000 requests per day), but it will be reduced every two weeks until it reaches 500 requests per day, which is the same as for V.2.9. Two weeks later, all V.2.4 requests will be redirected to V.2.9 for processing, and two weeks after that, V.2.4 will be closed down altogether.
The RoMEO API has so far provided two output schemas, defined using the
&versions=legacy- returning permission data for pre-prints and post-prints only. This is currently the default option.
&versions=all- returning permission data for pre-prints, post-prints, and publisher's version/PDF.
From the 11th November 2013, the default option will be changed to
&versions=all, and two weeks later the
legacy option will be removed completely.
Version 2.9 of the API was released in summer 2011, and the time has come for us to stop supporting the previous version (V.2.4). The next version of the API will be radically different, and it will be easier for us to help users upgrade from one version rather than from two.
The API is the most heavily used part of the RoMEO service, at times receiving over one million requests per day. This level of usage sometimes overloads our servers, which affects the availability of the service. Our usage logs indicate that certain unregistered users account for the majority of the heavy API usage, and the patterns of usage further suggest that they are using the API very inefficiently. By insisting that heavy API Users register for access keys, we will be able to initiate dialogues with them to eliminate or minimise the difficulties they cause.
The need to support the legacy output schema has been holding back the development of SHERPA/RoMEO. In any case, most users want data on permissions for publishers' versions/PDFs in addition to pre-prints and post-prints (authors' submitted and accepted versions respectively). Removing the legacy option will let us improve the quality of the data and improve performance.
The changes will be made over a two month period, in order to give API users time to upgrade their applications. The changes should all be completed by Monday 25th November 2013. Here is the detailed implementation schedule:
|16-Sep-2013 -||The limit for unregistered users of V.2.4 will be reduced to 50,000 requests per day|
|30-Sep-2013 -||The limit for unregistered users of V.2.4 will be reduced to 5,000 requests per day|
|14-Oct-2013 -||The limit for unregistered users of V.2.4 & V.2.9 will be fixed at 500 requests per day|
|28-Oct-2013 -||All requests to API V.2.4 will be redirected for processing by V.2.9|
|11-Nov-2013 -||The default schema for API output will be changed to return all article versions (pre-print, post-print, and publisher's version/PDF)|
|25-Nov-2013 -||API V.2.4 will be closed down, and the legacy output option (pre-print & post-print only) will be removed|
Register for a free API Key, if you have not already done so, especially if you are a regular API user or your applications make lots of API requests. Registration only takes a few minutes. There is a presentation on how to register for an API key and how to use it at: http://www.sherpa.ac.uk/romeo/RoMEO-API-Keys-2011-10-04.pdf.
API Keys are strings of letters and numbers - e.g. '
lq83AIL5bs7'. You can only use the API up to 500 times per day without an API key. Using an API key removes this limit and has a number of other benefits.
Register for your free API Key at: http://www.sherpa.ac.uk/romeo/apiregistry. If you have more than one application that uses the API, we recommend that you have separate API Keys for each application. This will let us provide you with specific support when necessary.
Review and upgrade your applications to:
- Ensure you have included
&versions=allin your list of arguments.
- Ensure you have included your access key (
&ak=) in your list of arguments.
The best approach is to define a root URL in a variable, to which you can then add your query arguments. E.g.:
http://www.sherpa.ac.uk/romeo/api29.php?versions=all&ak=lq83AIL5bs7[...add your query arguments here]
Modify your code to handle the additional
<pdfversion />data that the API returns, if you have not used the
Technical Manual - http://www.sherpa.ac.uk/romeo/SHERPA%20RoMEO%20API%20V-2-9%202012-10-04.pdf
API Efficiency Tips - http://www.sherpa.ac.uk/documents/Millington-OAI7-poster.pdf