Discovering drug targets gets faster — our API upgrades to v3
We just rolled out a new version (v3) of the REST API for the Open Targets Platform.
As part of this upgrade, we added new analysis and exposed additional methods. We have also improved our backend performance to a level that allows us to lift the need for user authentication (thank you elasticsearch 5!).
What changed?
Infrastructure
We changed the technology we use to run our API in production. We are now relying on the Google App Engine service, and we are deployed globally in 3 region: Europe, North America and Asia.
Our users can get data more rapidly, since our servers are closer to their geographical location and our content is cached by a CDN. We can also respond to changes in user demand by automatically scaling our API and main database backend.
URL
The new API is now exposed at https://api.opentargets.io and the base path is changed to be https://api.opentargets.io/v3/platform (note this is only the base URL; to retrieve some data you have to make a more specific request )
Pagination
Moving to elasticsearch 5 in the backend means we can now serve all the data we have about targets and diseases without stressing our database. The main improvement is coming by the way we paginate to get a large set of results.
In v2 of our API you would have used a combination of size and from parameters to get the 5.300.000th element of from /public/evidence/filter. It worked, but was very heavy for the backend. In v3 we are now making use of new functionalities in elasticsearch 5 to get to that 5.300.000th element that are far more efficient.
For each query you’ll do in /platform/public/evidence/filter and /platform/public/association/filter a next object will be returned.
To get to the next page you will need to simply pass the values in the next object to your new query.
and keep doing this you can get to the 2.603.229th element.
For back-compatibility, you will still be able to use the old size and from parameters to paginate, but up to a maximum of 10.000 elements.
Authentication and fair usage
With the new pagination method we are now in a place to issue every user a very high allowance on using our API, that should support almost any use case we can think of. There is still a fair usage limit, but should never stand in your way. If it happens please let us know
As a result of this we are deprecating our current authentication scheme. If you have an API key you will still be able to use it, but it will not affect your allowance. the new allowance is higher than any authenticated user had before.
New methods
There are two new methods that allows you to get similarity scores for targets and diseases based on the platform data.
/v3/platform/private/relation/target/{target_id}
will return a list of targets sharing a similar pattern of association to diseases.
/v3/platform/private/relation/disease/{disease_id}
will instead return a list of disease sharing a similar pattern of associated targets.
We use these data in the platform on both the target and disease profile page, you can go and have a look under the “similar targets” and “similar diseases” tabs.
We are in the early stages of these endpoints so they are kept in the “private” methods because they might change in the near future.
v2 still available
Since this version brings in breaking changes, we are keeping online the API v2 at the old address: https://api.targetvalidation.org/api/latest/
You’ll be able to keep running your code on the old API until the end of November, but the data will not be updated in that version.
We strongly encourage you to start migrating to v3 asap to access new data, and new methods.
Stay tuned.
