3.0 to 4.0 The new Atlas API

Last time at the new improved MetaTalks • Fred • Covered the history of Atlas (née URIplay) and what it does • Explained how the new Atlas deer release differs from what came before • Tom • Had just given us stable content IDs • This will be important later

Topics for today (vcfm?*) • Focus on new 4.0 API • What's different • Why *groan…

Design principles • Use plurals for resource types • Resource type URIs represent a collection of all resources of that type • Resource type URIs support querying of resources of that type • Every resource has a single canonical URI under its resource type • Support the common use cases in simple, obvious ways • Ensure a guaranteed, consistent speed of response for more complex queries

Yes, the URIs are gone • It’s not that 3.0 wasn’t RESTful - it was • Atlas and URIplay have always been very of the web • URIs as IDs make it hard to support things like POSTs, or PUTs to subresources • They’re also hard to pass round in URLs and for other people to use • So the URI of URIplay is now gone • All resources in Atlas now have an Atlas-generated web-safe ID

Content requests • Before • /3.0/content.json?uri=http://www.bbc.co.uk/programmes/b006q2x0 • After • /4.0/content/d9t.json

Content requests • But you can still look up by URI • /4.0/content.json?aliases.namespace=uri&aliases.value=http://www.bbc.co.uk/ programmes/b006q2x0 • Aliases provide a powerful new mechanism • /4.0/content.json?aliases.namespace=gb:bbc:pid&aliases.value=b006q2x0

Schedule requests • Before • /3.0/schedule.json? publisher=bbc.co.uk&from=2013-07-17&to=2013-07-18&channel_id=cbbh • After • /4.0/schedules/hkqs.json? source=bbc.co.uk&from=2013-07-17&to=2013-07-18

Topic requests • Before • /3.0/topics/vpfv.json • After • /4.0/topics/vcfm.json

Topic content requests • Before • /3.0/topics/vpfv/content.json • After • /4.0/topics/vcfm/content.json

Where are the differences? • Deliberately tried to keep things similar to ease migration • Two things are very different • Annotations • Content filtering

Annotations • 4.0 returns only IDs by default • Much like in 3.0, annotations add fields or groups of fields to the response • But in 4.0, they are scoped

Annotations - scoping • Different annotations can be applied to different resource types in a response • This is done using a dotted syntax • /4.0/schedules/hkqs.json?source=bbc.co.uk&from=2013-07-17&to=2013-07-18 &annotations=content.description,content.topics,channel.detail

Annotations - default scoping • The current resource type is implied • /4.0/content/d9t.json? annotations=description,topics,topics.topic.description • /4.0/topics/vcfm/content.json? annotations=description,topic.description

Filtering • Deer gives us the foundation to support flexible querying at scale • Filters will be built out as use cases are proven • Our general rule: • The URL that represents the collection of all resources of the type you are looking for is used to query for resources of that type • /4.0/channels.json?title=Film4

Content filtering • Content is a special example as there are multiple content resultsets • /4.0/content • /4.0/topic/:id/content • etc • All of these behave consistently

Content filtering • The following are equivalent • /4.0/topics/vcfm/content.json?topics.topic.relationship=about • /4.0/content.json?topics.topic.id=vcfm&topics.topic.relationship=about • The first is just syntactic sugar for the second

Other nice things • Content negotiation • Faster, more predictable performance • Almost: Tidied up representations

API 4.0 Next Steps • Tidy up the representations • Channels • Start migrating people to schedule • Genres • More flexible content filtering • Versions

Bonus: Atlas Future (unordered) • API is important, but it’s not everything • Realtime equivalence processing • More granular equivalence merging • Self-service data requests and key configuration • Change history