Changes to our versioning strategy.

When we released version 1 of our API in September 2014 then we decided on using HTTP’s content negotiation mechanism as documented here.

In summary, when you request a version 1 resource then you specify the accepted resource in the Accept header eg.

GET /documents?limit=125 HTTP/1.1
Accept: application/vnd.mendeley-document.1+json
Authorization: Bearer MSwxNDA5N…T1I5dnhPa0U

All clients were “very strongly encouraged” to include version information in your application’s requests so as to be able to predicate the behaviour from those requests.

Why are changing our approach to versioning?

Unfortunately, we didn’t lock down the Media Types we selected. Many clients are making calls using wildcard calls in the Media Types.

We should have made the implications of accepting all future API versions clearer to all clients up front. But we didn’t and so we would have to break many clients to fix this appropriately. We also have some other internal technical reasons which lead us to this decision.   

So as to avoid having to break many clients then the technical team made the decision to move the versioning information into the URI. This means that when we release version 2 of the ‘Documents’ API the request above will look like this:

GET /documents/v2?limit=125 HTTP/1.1
Accept: application/vnd.mendeley-document+json
Authorization: Bearer MSwxNDA5N…T1I5dnhPa0U

What are we changing?

All new endpoints will now contain the version information in the the URI and the Media Types will no longer contain the version number in it either.

Version 1 – Retrieve a collection of groups

curl 'https://api.mendeley.com/groups' 
 -H 'Authorization: Bearer <ACCESS_TOKEN>' 
 -H 'Accept: application/vnd.mendeley-group.1+json'

Version 2 – Retrieve a collection of groups

curl 'https://api.mendeley.com/groups/v2' 
 -H 'Authorization: Bearer <ACCESS_TOKEN>' 
 -H 'Accept: application/vnd.mendeley-group-list+json'

Version 1 – Retrieve a single group

curl 'https://api.mendeley.com/groups/9da69ed0-9d44-3d5f-b999-970f41c94c35' 
 -H 'Authorization: Bearer <ACCESS_TOKEN>' 
 -H 'Accept: application/vnd.mendeley-group.1+json'

Version 2 – Retrieve a single group

curl 'https://api.mendeley.com/groups/v2/9da69ed-9d44-3d5f-b999-970f41c94c35' 
 -H 'Authorization: Bearer <ACCESS_TOKEN>' 
 -H 'Accept:application/vnd.mendeley-group+json'

A word on Media Types

The Media Types that we use in version 1 all follow this pattern.  

application/vnd.mendeley-<RESOURCE_TYPE>.<VERSION>+json

The Media Types that we use in version 2 will follow this pattern.

application/vnd.mendeley-<RESOURCE_TYPE><NONE or -list>+json

For requesting a single group by id then you would use:

application/vnd.mendeley-group+json

For requesting a group collection then you would use:

application/vnd.mendeley-group-list+json

Impact on clients

You can use both version 1 and version 2 resources together. Clients must remember to switch their URIs and their Media Types appropriately.  

Errors

  • HTTP 406 –  Check you have set the appropriate headers.  
  • HTTP 415 –  One or more of the media types you have set in your headers is not acceptable.

Gotchas

You have to set the HTTP Accept header to empty when doing a delete to indicate you are not expecting a response. This is to maintain backward compatibility with version 1.  

If you see this error message?

{“message”:”The Accept header contains forbidden wildcards, it must be specified with a value from: [application/vnd.mendeley-group+json]; this is to ensure backwards compatibility”}

If you see the a message similar to this above then it means that you have used an unacceptable Media Type in your Accept header.

Development Tokens and Beta Endpoints

All Beta endpoints require an additional Development Token. These tokens live for a period of 90 days. This is to allow for reasonable amount of testing by clients of a beta endpoint.  You will find all details on the Development Token generator page.

Feedback

We would love to hear how this is impacting you or if you are having issues with understanding it – email api@mendeley.com

 

2 thoughts on “Changes to our versioning strategy.

Comments are closed.