Saturday 12:10 p.m.–12:55 p.m.

Designing Poetic APIs

Erik Rose

Audience level:
Best Practices & Patterns


The language you speak determines the thoughts you can think. Thus, API designers (and that includes you, if you've ever coined a function) have a great duty, as language inventors, to expand the mental canvases of those who come after. We'll concretize that into 7 hallmarks of good APIs, pulling examples (and bloopers) from popular Python libraries.


Designing APIs is one of the hardest tasks in programming. Besides solving your immediate problem, you also must accomodate unknown future ones—and fit nicely into other people's brains while you're at it. Can we codify this practice to steer us clear of the worst mires? I think we can. Let's examine some API successes and bloopers, factoring up the good patterns to yield a discussion of... * Extraction over invention * Brevity * Consistency * Composability * Simple data * Grooviness * Safety ...spiced with flavors from anthroplogy, psychology, and history. Armed with a pre-flight checklist of common API foibles, you'll be able to avoid many common mistakes and craft elegant APIs which make for short, understandable code; few errors; and happy programmers.