When we first started to build the open-source backend server, Appwrite, our goal was to make developers life easier. A lot of the tasks between different projects and even companies are complex, repetitive and can easily be abstracted, and that’s exactly what Appwrite is trying to do.
Appwrite is providing 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 integrations to our API with different tools and technologies.
Building a Great Open Source Project Is Not Only About Writing Great Code and Uploading It to Github
For Appwrite to be able to make an impact on developers we wanted to make sure that we treat both our documentation and our SDKs as a first-class citizen and not as something we have to figure out in a later stage of the development lifecycle.
Declaring Everything
Appwrite backend is using 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 that 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 should HTTP requests to this route 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 it makes 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-in 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 5 different languages (and we keep on counting up). Normally, this work was 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 alike. 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’s matter to us, making developers life easier.
About Me
I am Eldad Fux, a Software Architect, CTO, open source enthusiastic and the creator of appwrite.io. You can follow me on twitter: https://twitter.com/eldadfux
Latest comments (0)