in with the new
Deer is currently in beta and scheduled to replace Owl (the current version) in January of next year. A lot of lessons have been learned over Owl’s lifetime and it’s pretty easy to see those lessons reflected in Deer’s code base. We completed some work last week to support a certain feature in Deer, as this was my first experience working on Deer I thought I’d write about a particular improvement I liked.
Annotations are provided as query string parameters in the form of comma-separated values to the key of ‘annotations’. They tell Atlas what to show you for your query and how it should be presented. This isn’t new and has been around for a long while. What is new is how they are used internally by Deer.
old and busted
In Owl the set of annotations provided with a query get passed around a bunch of classes which simplify the internal complex model that Atlas uses for equivalence and figuring out what to show you. The result of annotations being little more than markers is lines and lines of this…
These set the desired data on the simple item, which is serialised by Gson and then dropped out the endpoint.
In Deer there is no simple model, which means we need a new way to decide how to output stuff. This is where the new annotations come in: rather than just being markers for if statements, they have function. Annotations exist as a component of our custom JSON serialisation library and each implement a small part of functionality that produces the JSON you see out of a v4 endpoint. An annotation is mapped to a Java type and called upon whenever the API layer needs to turn said type into JSON.
This keeps output and display logic away from the business logic that goes on when executing queries, as well as making it much easier to add new output logic. The choice of writing our own custom JSON serialisation code was “not a decision taken lightly” but nothing else gave us the flexibility we needed.
The API it exposes does a good job of hiding the nastiness of composing strings of text into valid JSON and provides tighter control over what our endpoints spit out. I’ll probably write about the JSON serialisation in more depth at some point :).
Thanks for reading.