Occasionally at Red Hat we have a “Day of Learning” where we get to spend time learning about technology of our choice.
I spent some time listening to various AI explanations which were suggested readings for the day. Nothing too surprising but also not exactly engaging to me. Maybe that’s because I grew up with a statistics professor for a father.
So while that was playing I spent a little time learning how the GitLab API works. Immediately it stood out that one of the primary challenges in presenting UI for such an API would be in bridging GListModel to their implementation.
So I spent a little time on the architecture for how you might want to do that in the form of a Gitlab-GLib library.
Pagination
There are essentially two modes of pagination supported by GitLab depending on the result set size. Both methods use HTTP headers to denote information about the result set.
Importantly, any design would want to have an indirection object (and in this case GitlabListItem) which can have it’s resource dynamically loaded.
Resources (such as a GitlabProject, or GitlabIssue) are “views” into the JSON result set. They are only used for reading, not for mutating or creating resources on the API server.
Offset-based Pagination
This form is somewhat handy because you can know the entire result-set size up front. Then you can back-fill entries as accessed by the user using bucketed lazy-loading.
When the bucketed page loads, the indirection objects are supplied with their resource object which provides a typed API over the JsonNode backing it.
This is the “ideal” form from the consuming standpoint but can put a great deal of load on the GitLab server instance.
Progressive Pagination
The other form of pagination lets you fetch the next page after each subsequent request. The header provides the next page number.
One might expect that you could use this to still jump around to the appropriate page. However if you are not provided the “number of pages” header from the server then there is not much you can do to clamp your page range.
Conclusion
This was a fun little side-project to get to know some of the inner workings of the API backing what those of us in GNOME use every day. I have no idea if anything will come of it, but it certainly could be useful from Builder if anyone has time to run with it.
For example, imagine having access to common GitLab operations from the header bar.
