How We Integrated Our Docs and SDKs As First-Class Citizens of Our Coding Process
Building a great open-source project is not only about writing great code and uploading it to GitHub
When we first started building the open-source back-end server, Appwrite, our goal was to make developer’s lives easier.
A lot of the tasks in different projects and even companies are complex, repetitive, and can easily be abstracted, and that’s exactly what Appwrite is trying to do.
Appwrite provides developers with a set of REST APIs and tools that help abstract the complexity and help developers build apps much faster and a lot safer.
But building a great open-source project is not only about writing great code and pushing it to GitHub. It’s about building a great community, having verbose and up-to-date documentation, and allowing easy integration into our API with different tools and technologies.
For Appwrite to be able to make an impact on developers, we wanted to make sure that we treated both our documentation and our SDKs as first-class citizens and not as something we have to figure out at a later stage of the development lifecycle.
Declaring Everything
The Appwrite back end uses a declarative approach to add new labels and metadata to each of our API routes.
This approach forces each Appwrite developer to define the route user input, validation rules, method description, SDK class names, and the SDK method names (as described in the figure).
Not only do we declare simple metadata about our routes, like their descriptions or SDK method names, but also complex settings like their rate limit thresholds, access control permission, and whether HTTP requests to this route should be audited in the user account or not.
When looking at our route definition, we know exactly what it is going to do on stage and in the background.
Thanks to our declarative approach of defining new routes, we were able to make sure that all the metadata we needed is being set and used properly.
Using the declarative approach has been a great benefit to our project. Not only does it make the code easier to understand, but this metadata can also help us automate our work process.
Automation, Automation, Automation
To make sure both our SDK and documentation stay up-to-date with any of our code updates, we used our app object to fetch all routes and generate an open-api.json file.
Thanks to the fact that our routes are very declarative, we had all the information we needed about our API, built into our code.
Now, that we had an open-api.json file describing our entire API, we could use it to generate both our docs and our API as part of our CI or development lifecycle.
Now We Can Try and Make a Difference
Instead of writing tedious documentation as an afterthought or having multiple back and forward cycles to make sure developers update their changes, we created a process that gives us peace of mind, great documentation, and a lot less work.
Our SDKs are being generated and pushed automatically to our GitHub repos constantly in five different languages (and we keep on getting more).
Normally, this work needed to be done by multiple developers that have different tech backgrounds. Thanks to our declarative approach, this job is done by our humble and hard-working CLI tools, instead of us.
Declaring and treating both our docs and SDK definition as part of our coding process helped us change our mindsets and process.
We saved a huge amount of time, we are no longer in a race to keep our ecosystem synced and we can focus on what matters to us, making developer’s lives easier.
