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

Eldad A. Fux
Sep 7, 2019 · 3 min read
Photo by Headway on Unsplash

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).

Our routes have all the metadata we need to make it tick.

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 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 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.

Better Programming

Advice for programmers.

Eldad A. Fux

Written by

Software Architect, CTO, open source enthusiastic and the creator of the open-source appwrite.io. You can follow me on twitter: https://twitter.com/eldadfux

Better Programming

Advice for programmers.

More From Medium

More from Better Programming

More from Better Programming

More from Better Programming

Fun Side Projects That You Can Build Today

3K

More from Better Programming

More from Better Programming

The Zero-Dollar Infrastructure Stack

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade