A presentation given by David Biesack, Chief API Officer at Apiture, at our 2024 Austin API Summit, March 12-13. Session Description: API Design is truly an art. While ChatGPT can spit out seemingly detailed APIs, there is still much to be said for well-crafted, consistent APIs designed by organic intelligence, in a broader context, with the consumer and Developer Experience in mind. A good (or dare we dream, great) Developer Experience (DX) is an important aspect of API design and the success of your API program. Attendees will grok the interplay of API design, patterns, and language constraints and limitations. See how and why artful API Design Matters to DX and "good" API outcomes, and why fluency in the myriad languages of APIs matters. Learn how choosing guiding principles can shape all your APIs for success. Learn how to stay relevant as an API designer when the API generating robots are breathing down your neck.

1. THE ART OF API DESIGN
DAVID BIESACK
CHIEF API OFFICER, APITURE

2. About Me
• Software professional for 38+ years
• I've been de
fi
ning APIs for most of that time (libraries/
frameworks in C, SAS, Java etc., then RESTful APIs)
• Headed SAS’ API Center of Excellence 5+ years
• Joined Apiture when founded in 2017; now Chief API O
ffi
cer
API design | evangelist | governance | DX
linkedin.com/in/davidbiesack/
fosstodon.org/@DavidBiesack
apidesignmatters.substack.com
github.com/DavidBiesack

3. API DESIGN IS …

4. API Design is….
• Understanding business requirements within the application domain
• Translating Requirements into an API that delivers the needed business functions
• Creating a durable abstraction which
• is
fi
t to the problem/product at hand... and others to come
• is comprehensible/usable (Developer Experience)
• isolates clients from change and implementation details that should not impact
them
• can evolve over time

5. API DESIGN IS AN ART

6. API Design is an Art
Each API is a Commissioned Work o
Requires some degree of Creativity o
API Designs [should] have aesthetics o
Beauty - Elegance - Balance - Harmony
API Design is a Right-Brain Activity o

7. The Role of Creativity in API Design
Is Creativity (Novelty) Welcomed? o
Creativity is in Con
fl
ict with Developer Experience o
Creativity is in Con
fl
ict with Consistency o
Creativity Ignores Reuse o
Creativity Increases Learning Curves o
Crea
ti
vi
ty
:
Th
e use of
th
e
imagina
ti
on or original ideas,
especia
ll
y in
th
e produc
ti
on of
an ar
ti
s
ti
c work.
- Oxford English Dic
ti
onary

8. The Role of Creativity in API Design
APIs must be Utilitarian
APIs must value Function over Form,
Substance over Style
A “beautiful, elegant” API that no one can use is
an Abominable Pretender-Imposter

9. API DESIGN IS A SCIENCE

10. API Design is a Science
o We can study APIs (…easier if they are de
fi
ned using API
speci
fi
cation languages)
o We can identify/discover Patterns
o We can apply rigor, methods, and standards to API Design
o We can learn from others
o We can evolve our practice
o We can improve the State of the Art of API Design
o API Design is a Left-Brain Activity

11. API DESIGN IS AN ACT OF INTELLIGENCE

12. API Design is an Act of Intelligence
API Design weighs multiple competing forces
• Domain Analysis / Modeling
• Solve the problems at hand
• Security, Attack Vectors
• Compliance / Legal
• API Surface Area
• Developer Experience
• Ease of Use
• Clarity; Conceptual Integrity;
Can be Understood; Mental
Model; Cognitive Load
• Completeness
• Can be implemented
• Consistency, Symmetry
• API Evolution
• Enablement (OpenAPI,
AsyncAPI, SDKs)

13. API Design is… The Art of Making
Decisions
Choosing 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 | Hypermedia | REST vs. RPC vs…
Naming things ( https://netapinotes.com/the-necessity-of-naming-in-apis )
IOW: API Design is a Whole-Brain activity

14. On AI
• I’ve been following AI for 38+ years
• I’ve learned to not set a bar that AI won’t clear
•The
fi
eld of API Design is not “special”
• Reality Check:
• Many companies succeed with Crappy APIs…
• …Crappy APIs that are designed by humans that may be no better than or even
worse than APIs that a generative AI could produce
• … but we can’t rely on that continuing….
•

15. On AI
Main Risk: Everybody thinks
everybody else’s job is easy.
• aboard.com/podcast/startup-year-in-review/
TANSTAAFL | YGWYPF

16. On AI
Current AI technologies 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
fi
t your domain?
Do those APIs solve similar problems?
Do those API styles match your developers’ needs?

17. On AI-Generated API Designs
An API Designed by an AI trained on Tons ‘o [Open Source] Training
Data….
...is an API Designed by Committee
Is an API Designed by [Reverse] Crowdsourcing
Conjectures:

18. API generating robots breathing
down your neck?
Having an AI write your API de
fi
nition is like pushing a horse with a rope….
API design through Prompt Engineering
Will an AI challenge requirements that are poor or not articulated well
To succeed, and AI needs to participate in PR reviews and other human
feedback - true arti
fi
cial general intelligence?
We have to be (can be) better than the AI
We have to do the
fi
rst 20% and the last 20% that are hard

19. Good APIs….
Are “Frustration Free Packaging”
Obvious, Comprehensible, and Intuitive - an Open Book
Reveal their intent (self-explanatory)
Direct Mapping of the problem domain
Lead to correct and e
ffi
cient solutions
Lead away from incorrect solutions
Are a joy to work with
Can be Beautiful and Elegant and Pragmatic - highly usable

20. API Design by AI
An AI is a software artifact
As such - Not to be judged good or bad
An AI that designs APIs is not good or bad
Just as a person that designs APIs is not good or bad
What we do with the AI is subject to judgement
We can judge API Design Outcomes

21. Is using an AI as a Tool for API Design so
different from….

22. Is using an AI as a Tool for API Design so
different from….
Consulting books…

23. Is using an AI as a Tool for API Design so
different from….
Attending courses and workshops…

24. Is using an AI as a Tool for API Design so
different from….
Absorbing a ton o' web sites...

25. Is using an AI as a Tool for API Design so
different from….
Subscribing to (and watching) a YouTube Channel....

26. Is using an AI as a Tool for API Design so
different from….
Reading a bunch of blogs....

27. Is using an AI as a Tool for API Design so
different from….
Consulting a colleague...

28. Is using an AI as a Tool for API Design so
different from….
Using AI tools is different, qualitatively and quantitatively
Notably:
• The ability to attribute the knowledge sources
• Consent to [re]use intellectual property
• Compliance and regulatory concerns
• Our ability to assign responsibility and accountability for API Design outcomes

29. API generating robots breathing
down your neck?

30. We are not unique in feeling
threatened...

38. 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