Today, I’d like to show off our new documentation site dedicated to SourceHut’s (and hence sr.ht’s) GraphQL APIs: docs.sourcehut.org.
Our work to move from the legacy REST API to a GraphQL API is still ongoing, and certain features we are aiming for (such as federation) are still missing. Nevertheless, it is already the best - and preferred - way to programatically interact with SourceHut instances.
If you’ve never used GraphQL before, there will be a slight learning curve. But we aim to make our documentation as helpful as possible, for beginners and experts alike.
At the core of each GraphQL API, there is a schema that defines the data types and operations that the API makes available. This schema can be considered a machine readable API documentation. The schema language also has first-class support for comments, to make it more accessible to humans as well. Yet, even with comments, the presentation of a raw schema is not exactly the most ergonomic way for a human to learn about an API.
However, given that all information is contained in the schema in a machine-readable way, it is quite easy to transform it into a form that is much more suitable for human consumption. Such tools are called GraphQL documentation generators. There are plenty of them out there, and we evaluated several. But none really checked all the boxes we were aiming for:
- Entire API output on a single page, so
Ctrl+fis useful - Little to no JavaScript
- Good support for custom directives
- Not too opinionated about the CSS/HTML structure
And so, I couldn’t resist: I wrote my own. You almost can’t call it a documentation generator, because it does nothing but throwing a specific object at a template you have to supply. But this also makes it powerful: the template has access to pretty much any aspect of the provided schema. These templates are key here, so if you are interested, you can find the templates for our documentation at git.sr.ht/~bitfehler/docs.sourcehut.org.
Given that we probably would have ended up writing a bunch of templates anyway (to properly customize the output of other tools), the result is pretty satisfying. Gockel is an extremely simple tool, and it will be easy to add features should the need arise. The underlying schema object that it exposes contains a lot of information, so there are many avenues to explore for improving the documentation.
Even though we ended up not using it, I would like to give credit to spectaql - it was the most promising candidate out of the existing tools I evaluated, and the current layout of docs.sourcehut.org is certainly inspired by its default theme.
For now, I hope docs.sourcehut.org will help you navigate SourceHut’s API. We are just getting started here, so there are likely some rough edges. If you find any bugs or have any ideas for improvement, please let us know.