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:
-
Register a new API key at guardian.mashery.com. Your old key won’t work.
-
Update your app. Use your new key and change the API domain from content.guardianapis.com to beta.content.guardianapis.com.
-
Everything should Just Work. If it doesn’t, let us know.
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:
- Faster response times.
- Faster availability of newly published content and updates.
- More sophisticated rights management, making more of our content available.
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.
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.