Good, Bad, and Ugly APIs: A FutureTalk with Michele Titolo [Video]

This article was written by Christian Sinai. Christian Sinai manages the FutureTalks speaker series at New Relic. He is a former architect (emphasizing sustainable design), and tech startup entrepreneur. View posts by Christian Sinai.

At the latest New Relic FutureTalk, app developer and CTO of Women Who Code Michele Titolo shared her hard-earned wisdom on the best (and worst) practices in API design and implementation. With more than five years’ experience building iOS apps, Michele has seen the whole spectrum of APIs, from the slick and successful to the clunky and downright dysfunctional. She takes great pride in building user-friendly apps, and understands that good API design is essential to delivering a positive experience for both developers and end users. In fact, emphasizing the value of simplicity and consistency, Michele showed that user experience should be front-of-mind for anyone working on an API.

“When it comes to building really fantastic APIs,” she said, “it’s a lot about the developer experience. But what it really ends up being about is the user experience. If you have a sucky API, it’s really hard to disguise that fact from your users.”

Keeping it Authentic

Michele Titolo

The ubiquity of mobile today means that all apps (and APIs) must be mobile-first, or at least mobile-friendly. And a key aspect of a positive mobile user experience is authentication. Michele recommended sticking with a widely used protocol such as HTTP Basic Auth, deployed over SSL. Alternative protocols such as OAuth, though fine for general Web use, can be problematic when it comes to mobile, often interfering with the typical mobile experience.

Michele also advised strongly against attempting any kind of DIY authentication. Her advice? Leave it to the experts: “There are some very smart people who create encryption methods and security protocols,” she said, “and you should probably let them do their jobs and use their products.”

Sending the Right (Error) Message

Errors are inevitable. Incomprehensible error messages, however, are not. When you’re eagerly working on your API, errors and the messages they generate can slip pretty far down your priority list. But establishing a good system early on can pay dividends down the line. And the more descriptive (and readable) the error message, the better. That way, whether they’re encountered by developers or end users, those messages can actually be useful and constructive.

Otherwise, Michele cautions, you’re just saying, “There’s a problem!” without guiding your user towards a solution.

Caching Fast, Caching Right

Caching isn’t compulsory. But according to Michele, it should be—especially for API developers building for mobile, which today is pretty much all of them. She has worked with numerous APIs that didn’t cache, and in each case has run into problems. This is particularly frustrating because plenty of great HTTP standards already exist (a header like Cache-Control, for example) with everything you need built in. Just as DIY authentication can create unnecessary issues, attempting to process and cache data manually will slow things down. And that’s bad news as users increasingly demand speedy responses.

“People expect things to be really, really fast,” Michele said. “The more that has to be done on the client side, the longer it’s going to take, and the unhappier the user is going to be.”

And if your users aren’t happy, your API isn’t working as well as it should be—at least, not yet.

To learn more about API practices good, bad, and ugly, watch Michele’s full FutureTalk below:

For more information about our FutureTalks series, make sure to join our Meetup group, New Relic FutureTalks PDX, and follow us on Twitter @newrelic for the latest developments and updates on upcoming events.