Secrets of API Design – 3 insights from a veteran Software Architect

Imagine you are a Director of Software Architecture for an e-commerce company. You’ve designed e-commerce APIs for 12 years (and counting). What would you have learned?

Shawn Gerty has been leading Beanstream’s software design since 2002. The API world has changed a lot in that time: In 2008, one online API directory housed only 100 different APIs. Five years later, that number approaches 11,000.

Shawn is an interesting guy: he never turns on the lights in his office. The only light source is a small pyramid-shaped lamp, resembling glowing amethyst. His origins as a programmer are just as interesting: in the early 1980s he was an avid player of Dungeons & Dragons. Before long, he acted as Dungeon Master for his friends and created computer programs to organize his campaigns.

I spoke with Shawn about his API observations, which can be distilled into the following secrets:

1. Simplicity

“Keep APIs simple and lightweight… clear,” says Shawn. “A big part of Beanstream’s success: we’ve kept our APIs simple and flexible from the start. Scalable.”

I can attest. With a background in Creative Writing, then becoming Beanstream’s Technical Writer, I’ve been on a steep learning curve. But I’ve learned a lot – quickly. Shawn’s elegant API designs guided me through the, er . . . dungeon.

Gerty stresses the importance of software designers shouldering the burden of complexity. “The integration with the banks and acquirers is complex, but we’ve always handled that for merchants. We make it simple.”

But API design has not always been tricky.

“In the early days, designing APIs was easy, but there were no real implementation standards. You kinda did your own thing. SOAP came along full of features and simplifying integration, but it was bulky. REST has now gone back to basic HTTP requests, but with an implementation model that encourages good design.”

2. The more things change . . .

A good API, then, is built to last. “Well-designed APIs, from the past, still work the same,” says Shawn.

“The underlying communication layer has not changed that much. Browsers have been enhanced, but the communication layer is the same.”

So, as protocols come and go (where are you now, SOAP?), and browsers become more sophisticated (anyone remember LiveScript?), the underlying communications remain unchanged.

3. Work closely with merchants and external developers . . .

APIs, by their very definition, do not operate in a vacuum. We design them with the intention that integrations occur.

“It’s important to open up creativity to everyone. It opens up the customer base, and community. It doesn’t restrict people to one solution,” says Shawn.

He believes it’s this willingness to work closely with merchants that helped Beanstream in the long run. “It’s how we found ourselves in a leadership position early on: our APIs were based on customer need. We worked very closely with merchants, partners, and developers.”



Jack knows beans.

How to get them.
How to grow them.
How to protect them.

Jack will be around every once in a while giving his advice, in his weekly column Jack Takes Stalk