The Art of API Design
... and the science of API Design
This article is a re-presentation 1— a director’s cut, if you will — of my talk of the same name at the 2024 Nordic APIs Austin API Summit. My talk kicked off the “API Design track on the first day of the conference. You can view my talk on YouTube and other talks on the 2024 Nordic APIs Austin API Summit playlist
About Me
Software professional for 38 years
Have been defining “APIs” for most of that time
For many years, “APIs” were libraries and frameworks that I wrote in C, SAS, Java etc.
then I started designing REStful APIs
I Headed SAS’ API Center of Excellence for 5+ years
I joined Apiture as an API designer when it was founded in 2017. I now serve as Chief API Officer (API design, DX)
API Design Is
(This is my own take. You probably have a different definition - please share in the comments!)
Understanding Business Requirements and the problem(s) to be solved
Translating Requirements into an API that solves those problems
Creating a durable abstraction which
is fit to the problem/product at hand
is comprehensible/usable
isolates clients from change and details that should not impact them
can evolve over time
API Design is an Art
Each API is a Commissioned Work
The Role of Creativity in API Design
API Design artifacts [should] have aesthetics
Beauty - Elegance - Balance - Harmony
The Role of Creativity in API Design
Is Creativity (Novelty) Welcome in API Design?
Creativity is in Conflict with Developer Experience
Creativity is in Conflict with Consistency
Creativity Increases Learning Curve
Creativity Ignores Reuse
Using Greek letters or musical notes in API path elements is certainly creative, but that does not make the API good or usable.
Instead of being highly creative,
APIs must be Utilitarian
APIs must value Function over Form,
APIs must value Substance over Style
A “beautiful, elegant” API that no one can use is an
Abominable Pretender Imposter
API Design is a Science
(or at least a scientific endeavor)
We can study APIs (…easier if they are defined using API specification languages)
We can identify/discover Patterns
We can apply rigor, methods, and standards to API Design
We can learn from others
We can evolve our practice
We can improve the State of the Art of API Design
API Design is an Act of Intelligence
In my mind, API Design is a whole brain activity which employs both Art and Science, making it an act of intelligence.
API Design weighs multiple competing forces
Domain Analysis / Modeling (see API Design First is not API Design First)
Solve the problems at hand
Security (see Understanding the Language of API Security)
Developer Experience
Ease of Use
Clarity
Can be implemented
Consistency
Conceptual Integrity
API Evolution
API Design is… The Art of Making Decisions
API designers must choose from many alternate/possible design options
Use rubrics or decision procedures
Record and measure outcomes
Knowing when applying a pattern is the right decision… and knowing when it is not
CRUDL | HATEOAS | REST vs. RPC vs…
Naming things is a good summary of decisions that impact API design
On AI
aboard.com/podcast/startup-year-in-review/
Everybody thinks everybody else’s job is easy.
“… maybe Anna Indiana represents the first steps towards some sort of AI pop star. Maybe she could write a better song. Maybe she could be 50% good instead of 100% horrifying. But what I wish I could get across to our friends in the Palo Alto area is that the last 20% is really, actually, hard—not just in tech, but in writing, music-making, carpentry, middle-school teaching, cobbling—it’s a grind.”
On AI (continued)
Current AI technologies (generative AI, Large Language Models (LLMs) rely heavily on Tons o’ Training DataTM
What APIs will you use to train your API Generating AI?
Are the decisions made when creating those APIs correct?
Does the training data fit your domain?
Do those APIs solve similar problems?
Do styles match your developers’ needs?
Was your AI trained on poor API designs like Pet Store or crAPI … or worse? How do you know? How do you continue to know?
On AI-Generated API Designs
An API Designed by an AI trained on Tons ‘o [Open Source] Training DataTM….
Is an API Designed by Crowdsourced Committee
API generating robots breathing down your neck?
Having an AI write your API definition is like pushing a horse with a rope….
API design through Prompt Engineering
An AI is not (yet) going to challenge requirements that are poor or not articulated well
To succeed, and AI needs to participate in PR reviews and other human feedback - perhaps this requires true artificial general intelligence (AGI)
We have to be (can be) better than the AI
We have to do the first 20% and the last 20% that are hard
Good APIs….
Are “Frustration Free Packaging”
Obvious, Comprehensible, and Intuitive - an Open Book
Reveal their intent (self-explanatory)
Direct Mapping of the problem domain
Use the domain terms to increase comprehension
Lead to correct and efficient solutions
Are a joy to work with
Can be Beautiful and Elegant and Pragmatic - highly usable
Hope
We are not alone in feeling our place and our passion for creating great APIs is threatened.
A couple generations ago, computer scientists could have feared the next generation of computer scientists that would follow them, a new generation that might replace them.
Instead of cowering or quitting, they chose to build the software and write the great papers and books that passed on what they had learned, so that the field would continue to thrive.
(I have listed below some of my favorite books that shaped me as a computer scientist/programmer/technologist)
Structure and Interpretation of Computer Programs (SICP) by Abelson, Sussman and Sussman
The Design and Analysis of Computer Algorithms by Aho, Hopcroft and Ullman
Godel, Escher, Back: An Eternal Golden Braid by Douglas Hofstadter
The C Programming Language by Kernigan and Ritchie
Common LISP: The Language (CLTL) by Guy Steele
Design Patterns: Elements of Reusable Object-Oriented Software by Gamma, Helm, Johnson, Vlissides
Refactoring: Improving the Design of Existing Code by Martin Fowler
Principles of Compiler Design (The “Dragon Book”) by Aho and Ullman
These intelligent people made human decisions to continue, to pass on their knowledge to the next generation. They stood as giants so we could stand on their shoulders. I hope they inspire us to do the same
Other resources
One of the best news/podcast episodes I’ve listened to on AI and tech is the “Will AI Save the Internet? Or Break It?“ episode of the Ezra Klein show, featuring Nilay Patel
Not a “representation” in the REST sense :-)