I've been working through How to Design Programs recently. It's interesting to see how they walk people—especially newcomers—through the process of learning how to design programs. It got me thinking about how newcomers experience the world of API design.
Design-first and beginners
Many agree the design-first approach to API design is preferred—including experts and API design companies alike. The idea is to write an API definition like OpenAPI before writing a line of code. This stands in contrast to a code-first approach where API definitions are generated later from code. And though design-first is preferred, code-first is probably most common.
Consider what a beginner would need for a design-first approach.
- Experience and knowledge for designing applications (more on this later)
- An understanding of common URL patterns used in the industry
- A firm grasp on how to use HTTP methods and status codes along with their many nuances
- Knowledge of designing JSON documents through JSON schema
- Familiarity with formats like OpenAPI or API Blueprint
- Exposure to tooling for these formats
Beginners have to gain experience, knowledge, and understanding in API design before they can do design-first well. Good practices are spread across books, websites, and videos with varying degrees of consensus among practitioners on what truly is good. This takes lots of time and patience.
A quick search of the web for "how to design an API" will give recommendations like using plural names in URLs and HTTP methods as defined, but these fail to give direction for good design. It's up to the beginner to sift through the noise.
Pet-store-first driven API design
I've been working with APIs for several years now, and I'm sorry to admit I still have to copy and paste the Pet Store example to start writing an OpenAPI document. The same is true for me and API Blueprint's Polls example. I still need some visible guidance on both the syntax but also what is possible to define for the API.
But there is something deeper here than syntax. While these formats are great, they don't prescribe a way to design an API. You can design a wonderful API or a horrible API with any format.
This feels similar to the way How to Design Programs considers program design more important than programming. We can't teach newcomers things like variables, functions, loops, classes, and so on and expect them to be able to design a good program. Rather, we should teach methods for coming up with a good design.
Application-first driven API design instead
We talk about writing API definitions first, but I don't think it's possible to design a good API without understanding how to design a good application (an API is a programming interface to an application after all). Conversely, a well-design application can be used to drive good API design. If this is true, beginners should begin learning how to design applications and only then learn how to make those applications work across the web by way of an interface. Design the application first, then write the API definition.
It doesn't stop for beginners. This isn't something you move on from once you get good at it. This should be true for experts as well. Experts should be able to sit with domain experts and users and walk everyone through the design of an application before ever considering what the API looks like.
Everyone can design APIs
The authors claim in the preface of How to Design Programs that "everyone can design programs." They say the skills from program design can transcend industries. Good program design will shape a person's approach to any problems by giving them a systematic process for exploring the design. It makes me think the API design community could borrow these principles and practices to help lower the barrier of entry for newcomers.
If you want to see a good explanation of this approach, check out the video How to teach programming to loved ones. He goes through some of the reasoning behind how they teach programming design and then shows a demo of it in practice.
Top comments (0)