Supercharging the API User Experience
Great API definitions are hard to write. As outlined by James in a recent memo, striking the right balance between domain and technical and stable but extensible requires a great deal of time, energy and effort.
After all that work, many APIs fail at the last hurdle - not realizing their value creation potential because their developers fail to consider the user experience and accessibility considerations that ultimately drive adoption.
Put simply, the easier it is for services to be used, the more they will be.
The ingredients to a great API user experience
1. Documentation
Documentation is the only window a user has into your API - it has to be done right. But, at the same time, documentation is boring to maintain and takes up developer time that could be spent on building new features and offering more value to end users.
How do we ensure our APIs have robust documentation without falling in to the deep, dark abyss of maintenance?
2. Stability and consistency
APIs should not change dramatically or quickly and should still support users longgg after they've been deprecated. API URLs and client libraries should include versions in the URL or package, and any breaking change to the API should result in a bump of the major version. Backwards compatibility is important - you can't just remove things from and change your API willy-nilly or you'll break your clients' code. Big no no.
So how do we seamlessly integrate mechanisms for implementing versioning and backwards compatibility checks to ensure things like this don't happen?
3. Meeting your user where they are
The user-experience when integrating with your API should be an enjoyable one. This means client libraries in your users' favourite language that feel natural to adopt. It doesn't mean spending hours crafting custom wrappers on REST endpoints to make these libraries available.
How do we support diverse options for accessing APIs without spending time manually writing client libraries which need to be edited every time there's a change to the API?
Enter Alis Build
The Alis Build platform makes easy to use protos to define APIs and supercharge the user experience.
All of our APIs are defined using Protocol Buffers, which form the basis for everything that is created on Alis Exchange. After creating a proto, defining the API definition and releasing this definition, it enables us to automate many of the best practices that lie at the heart of creating great APIs.
1. Documentation
The core principles for documentation on Alis Exchange are:
- Documentation should be generated and not maintained.
- The process for creating documentation needs to live as close to the developer experience as possible.
Alis takes the process for creating and maintaining docs and seamlessly integrates it into the developer experience. Reference documentation is generated directly from the API definitions in your protos and custom documentation lives next to the protos. All you need to do is run an alis docs release and allow us to handle the rest. A couple files from the developer results in a fully generated docs website.
Check out docs.de.alis.services to see for yourself!
2. Stability and consistency
Alis has backwards compatibility checks and versioning baked into our process. When running alis proto release, breaking changes are immediately detected which prevent broken client libraries and auto-generated REST APIs from making their way into production.
$ alis proto release xmpl.br.resources-books-v1
ERROR rpc error: code = FailedPrecondition desc = protocol_buffer (protocolBuffers/xmpl.br.resources.books.v1) is not backwards compatible:
CONFLICT: "ListBooksResponse" field: "next_page_token" has been removed, but is not reserved [books.proto]API versioning is also enforced at the design level, as all newly created APIs must specify a version. This version is then carried through to the client packages and API URLs.
3. Meeting your user where they are
When running alis proto release client packages are immediately generated in Go, Python and Javascript, with support for many additional languages coming soon. REST APIs for traditional JSON support are also auto-generated.
Gone are the days of creating the impression that you support a range of languages when in fact you are simply making a REST call from the language. Also, no need to go through the efforts of updates when you add features to your API. You simply focus on your protos and ... I feel like I'm repeating myself now.
Ready to build your own APIs?
Want to start using next-generation tooling that will eliminate toil from your development process, turn your every-day developer into a quality software engineer and take your APIs from good to great? Reach out to us.