Atlas - 3.0 to 4.0

Continuing on from Fred's talk on owl vs deer, Jonathan gave a talk on the differences between the current Atlas 3.0 API and the upcoming version 4.0 on July 17th, 2013.

1. 3.0 to 4.0 The new Atlas API
2. 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
3. Topics for today (vcfm?*) • Focus on new 4.0 API • What's different • Why *groan…
4. 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
5. 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
6. Content requests • Before • /3.0/content.json?uri=http://www.bbc.co.uk/programmes/b006q2x0 • After • /4.0/content/d9t.json
7. 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
8. 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
9. Topic requests • Before • /3.0/topics/vpfv.json • After • /4.0/topics/vcfm.json
10. Topic content requests • Before • /3.0/topics/vpfv/content.json • After • /4.0/topics/vcfm/content.json
11. Where are the differences? • Deliberately tried to keep things similar to ease migration • Two things are very different • Annotations • Content filtering
12. 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
13. 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
14. 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
15. 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
16. 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
17. 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
18. Other nice things • Content negotiation • Faster, more predictable performance • Almost: Tidied up representations
19. API 4.0 Next Steps • Tidy up the representations • Channels • Start migrating people to schedule • Genres • More flexible content filtering • Versions
20. 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