The Art of API Design Apr 11, 2024 … 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. Welcome to the next article in The Language of API Design series. Rather than jumping into the middle of this series, I encourage new visitors start by reading The Language of API Design and scanning previous posts in the series. About Me My professional profile, davidbiesack.github.io 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 served as Chief API Officer (API design, DX) until March 2026, shortly after Apiture was acquired linkedin.com/in/davidbiesack/ fosstodon.org/@DavidBiesack apidesignmatters.org - Here! 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 __A__bominable __P__retender __I__mposter 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 one set of decisions that impact API design On AI Aboard “Startup Year in Review” podcast Everybody thinks everybody else’s job is easy. Aboard “Don’t Let the Robots Get You Down” podcast/ “… 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 Data™ 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? Pet Store API - Just Say No! On AI-Generated API Designs An API Designed by an AI trained on Tons ‘o [Open Source] Training Data&trade…. 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 Gödel, Escher, Bach: An Eternal Golden Braid (GEB:EGB) 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 (GOF) 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 1 Not a “representation” in the REST sense :-) Join the discussion Note: This article was originally published on the auhor’s API Design Matters Substack.