Let’s say you want to read a Tumblr post information from their API v2. Nothing special at the first look, but beyond the obvious parameters, there’s an interesting one: notes_info. The API designer thought to make this optional (it defaults to false) as to not overload the server and cause unneeded traffic with all the likes and reblogs your requested post might have – especially if popular.
https://api.tumblr.com/v2/blog/your-blog-to-check/posts?api_key=0ABCDEFGH&id=12345678¬es_info=true
And how will those notes look like? Well, the API documentation forgets to document that. Its last update is from 2011, the very year where the Swagger project was started so we can forgive them for the lack of documentation. But if we quickly try the API, it will – somewhat obviously – return only the first 50 notes. Obviously, because what if the post had a million notes?
[{
avatar_shape: "circle",
blog_name: "ablogname",
blog_url: "https://ablogname.tumblr.com/",
blog_uuid: "t:kjhlIU(/OLUGu7g",
followed: false,
post_id: "9873875387587638",
reblog_parent_blog_name: "anotherblog",
timestamp: 1592801102,
type: "reblog"
},
…
Now, HOW on earth could we paginate over these notes? The obvious answer is: no way, it’s an inner structure and the REST idea doesn’t allow for that. I mean, something like
https://api.tumblr.com/v2/blog/your-blog-to-check/posts?api_key=0ABCDEFGH&id=12345678¬es_info=true&offset=50
logically would apply to the response of the call. So, whenever Tumblr does an API update, maybe 2021 to celebrate 10 years since the last one, how about they make the notes first class citizens and let one access them properly.
https://api.tumblr.com/v2/blog/your-blog-to-check/posts/12345678/notes?api_key=0ABCDEFGH&id&offset=50
And as a modern OpenAPI and documented right? Like even the petstore of Swagger is? And while we’re talking about changes, discoverability wouldn’t hurt either – add a Link header! It’s official (together with the types next/prev/first/last) so should be fairly well known, and Spring REST supports it out of the box.
Link = https://api.tumblr.com/v2/blog/your-blog-to-check/posts/12345678/notes?api_key=0ABCDEFGH&id&offset=100; rel=”next”
That was just a silly and frustrated example. It doesn’t have to be offset pagination, it could be cursor pagination or anything. Just have it there, thank you!
(Published as part of the #100DaysToOffload challenge https://100daystooffload.com/)
Top comments (0)