API Design Should Be About Interactive and Tinkering

As a returning presenter at Gluecon, Sumit Sharma said before his talk Thursday that last year he spoke about API design — the same general topic he was about to speak on again. The difference this year, he said, is that he was adding the human element. “API design should follow a lifecycle. Machines and humans need to play nicely.”

Sharma is Director of API Strategy & Solutions at Mulesoft (disclosure: MuleSoft is the parent company to ProgrammableWeb). As such, he’s an evangelist for Mulesoft’s API product suite -- the Anypoint Platform for APIs  -- and is responsible for evangelizing the transformative power of APIs both internally and with customers.

His talk was entitled “Designing APIs for the Enterprise,” and he began by describing the old way of designing an API — which essentially was whiteboarding a spec. Now, he said, it’s evolved to much more of an interactive process that includes talking with developers, and helping “define the contract.”

He said the RAML API description is different — “its a good way to simplify API design, really as simple as an API could be. There’s not a lot of JSON in it.”

Sharma did a demo of a fictitious example: building an API for a jukebox. He used an open-source tool called “API Notebook,” which contains all APIs defined in RAML that many people have contributed. It is a JavaScript scripting workspace that lets you test-drive any RAML API. You can share use cases with a click by saving them as gists.
He continued his talk by focusing on the topic of API discovery. He said 1.0 was about searching, but that 2.0 is now about “tinkering” — search plus a Developer Portal. Tools like the API Notebook provide “a way of tinkering as discovery.”

Mulesoft’s Anypoint Platform for APIs (which Sharma evangelizes) connects any app, any device, and any API. It lets you build new APIs, design new interfaces for existing APIs, and more efficiently manage all your APIs using a single Platform. The platform includes an API Portal that promises to “make it easy to engage fellow coders, teammates, and customers at every step… Build an API for users, and they will code.”

It was clear from Sharma’s talk that ”interactive” and “tinkering” were the two hot takeaway words from his session. “At the end of the day, it’s all about things working with each other,” he said.

Sharma proudly declared tinkering as “a new way of discovery in my mind.” He believes the process he described in his talk is “a way to validate that I know people will want to work with my API.”

Be sure to read the next API Design article: Developer Experience (DX) is Key to a Successful API