Mendeley API – Blackout Testing

Today we performed something known as a “Blackout test” on the Mendeley Open API. As those of you who develop apps against this API know, we are planning to phase out OAuth1 authentication in favour of OAuth2 permanently from 2014-05-18.

We are doing this for a number of reasons:

1. Simplified authentication: OAuth2 doesn’t require clients to have a deep understanding of cryptography, which makes it much easier to use. You just need to worry about getting the right tokens and do your requests over HTTPS.
2. OAuth2 provides more flows so not only browser applications can use the API. OAuth2 provides a better user experience for installed applications like desktop or mobile applications.
3. You can specify more granular permissions in your application, which will make it more trustworthy.
4. Easier transition to updates on the Mendeley API.

If you are a developer who has built their app on OAuth1, you should already have migrated to OAuth2. If you have not done so yet, we have some guides to help you do this here.

What is a blackout test, and why is it a useful thing?

A blackout test can be defined as a planned, timeboxed event, when we will turn off a certain API to help developers better understand the implications of the eventual retirement of that API. In our case, we used a 1 hour period where the OAuth1 authentication endpoint was configured to respond to all requests with “HTTP-410 GONE”. This is the same response we  will return once the API is finally retired.

Hopefully this blackout test will help developers get a better idea of how the retirement of OAuth1 is going to affect their applications. In the perfect world, it would have zero effect. Furthermore, noticing a large spike in request failures blackout test can also act as a call to action for some developers who might have missed other announcements. We will also be analyzing our logs carefully to see how close we are to migrating all apps to OAuth2. This information will help us make a better decision on the full retirement of OAuth1.

The future of the Mendeley API

Moving forward, we have some pretty ambitious plans for the Mendeley API, and migrating clients to OAuth2 is an enabler for a lot of that work. Once all our clients are authenticating using the same protocol, we can start rolling out some great new API endpoints, and hopefully empower the creation of some brilliant apps on top of the Mendeley platform.
We’ve listened to your feedback and we want to provide the best platform we can. That’s why we’ll be releasing improvements in on the current API, specifically the Documents API, where syncing your documents has been simplified greatly (no more requesting the entire library every time), as well as new API endpoints to get your annotations or an improved search of the catalog.