Non-technical API Design Should Be Possible
Why aren’t most API Design tools helping non-technical people?
Most people who believe they work in API Design aren't. What they're actually doing is technical work on API definitions. API Design is still very focused on syntax, semantics, schemas, external references, attributes, error codes, you name it. All these things are important and necessary. However, they're not what API Design should be about. API Design lives at a level of abstraction above all the technical toil needed to make APIs work. Designers translate what consumers need into a plan of what an API should be. What are the tools and processes that can help? Stay with me to explore.
This article is brought to you with the help of our supporter: Speakeasy.
Speakeasy provides you with the tools to craft truly developer-friendly integration experiences for your APIs: idiomatic, strongly typed, lightweight & customizable SDKs in 8+ languages, Terraform providers & always-in-sync docs. Increase API user adoption with friction-free integrations.
To me, non-technical work is everything where I don't need to manipulate code or engage in any sort of machine configuration. Writing this text, for example, is non-technical work. Using a GUI to prioritize feature requests is also non-technical work. In essence, the work that happens to design what an API should be is non-technical. However, the work to define how an API behaves becomes technical. Identifying and documenting the functionalities of a new API is non-technical work. Creating an OpenAPI document for a new API is technical work.
So, in theory, one should be able to design a full API without touching a single line of code. This realization is something that I've been exploring for some time. As I wrote in 2019 in API Design, "the most important activity is making sure that whatever the API is providing is fully aligned with how users expect the application to behave and about their own experience." At that time, I hinted at a growing participation from Product Managers in the activities related to building APIs. That participation starts with the identification of the API consumer personas and their JTBD (jobs to be done) and ends with a prototype that stakeholders can try and provide feedback on.
The advantages of involving non-technical people in API Design from the get-go are clear to me. Understanding JTBD, for instance, helps you identify the challenges consumers have and can even guide you on what your API monetization should be. "If you understand that most user personas will probably use your API only once to complete a one-off task, then offering a subscription payment model might not be the best choice for generating steady revenue"—Building an API Product. Benefits are something else Product Managers understand because they're related to use cases. Not only can you directly use benefits to pitch your API to stakeholders, but you can also translate them into functionalities. You can even pick the API architectural style (REST and gRPC, among others) from the information available in user stories.
It's usually at the Functionalities stage that non-technical people hand off their work to developers, who will then work on data models and API definition. I don't agree with this approach because I think non-technical people should be able to work through all stages until they deliver an API prototype. Data models, for instance, are something a Product Manager can understand and define. Who can better comprehend the nature of the data than those who interact with stakeholders? The difficulty in modeling data doesn't come from a lack of knowledge of the data itself. Instead, it stems from the complexity of most data modeling tools. A similar thing happens with API prototyping. Given the right tool, prototyping an API shouldn't take more than a click on a button, if you know what I mean.
One tool that follows an approach that is friendly to non-technical people is Flotiq. You can literally go from having your data model defined to seeing an API working with one click. You don't even see the API definition ever. That's possible because the whole flow assumes you want to create a CRUD (create, read, update, and delete) of your data. Which is what most REST APIs need anyway. By limiting the functionalities, it simplifies what it can offer while making it easy to get an API spinning. However, you can attach specific logic to any of the CRUD operations if you wish to do so. You can, for example, add logic to validate a payload before your API stores it as a new object. You can either add the code directly using the UI or trigger a Webhook that runs whenever an operation is executed.
This approach lets you, as a Product Manager, define the whole API—including the data models—and see it working immediately. You can then validate it with your stakeholders and then hand off the work of adding specific logic to developers. What I see missing in this approach is the ability to reuse logic, either in the form of a library of components or by using an external service that you can activate via Webhooks. I will continue to explore the approach Flotiq is following and see what steps in the process can be improved.
I really like your blog! Your exploration of API design principles is always insightful. I've been focusing on improving my own skills, and I recently started using EchoAPI, which has made structuring my APIs much more intuitive.