Introducing the Content API v2

The Guardian are making some changes to the Content API, the principle service of the Open Platform. Here’s everything you need to know.

Cantlin Ashrowan

Published on Thursday, 17 July 2014

Content API  

Content API response
Content API response Photograph: The Guardian

Quick start

The new API is a faster, mostly backwards compatible version of the old one. You need to start using it by August 30th. More detail follows. If you just want to get started right away, follow these steps:

Why are we making changes?

We recently developed a new version of the Content API for our use internally. We’d like to share the benefits with our developer community, including:

What changes are being made?

The new version of the API is largely backwards compatible with the old one. The endpoints are the same as ever, the interchange format is unchanged, and most of the current filtering and output control features are still available in the new version.

We’re taking this opportunity to simplify the tiers of access. The new default access level for an API key is called “developer”. This allows access to everything you could get via the old “approved” tier.

For our partners there’s also a new tier, “rights-managed”, which replaces the old “partner” and “external-partner” tiers. Again, there is little practical difference between the old arrangement and the new one.

v2 dashboard
v2 dashboard: status.content.guardianapis.com Photograph: The Guardian

What features are being deprecated?

Because of rights issues, we generally don’t distribute images and videos through our API. In some special cases though partners have been able to access media like pictures and videos in our content through a feature called media assets. These are being replaced by a much better feature called elements. See here for guidance on migrating from assets to elements.

Other niche features like show-snippets and show-refinements have also been removed. See here for a complete list of all features and their status.

When is this change happening?

All clients should switch to the beta.content.guardianapis.com domain by August 30th. On that date we will update the old content.guardianapis.com domain to use the new service. Clients who have not migrated will start receiving errors due to their old key no longer being valid for the new service.

Will you be changing the terms of service?

Yes, but they will retain the spirit of the current terms. Stay tuned.

Continue reading

Navigating the Guardian Hacking Journalism at the MIT Media Lab