Developers are Users Too : Why the User Experience of Your API sucks #yourapisucks

Many thanks to those of you who came along to my talk on why your API sucks. There were some great discussions during and after, and I hope I’ll be seeing slightly fewer reasons to tear my hair out in the near future.

A few things that people mentioned that I want to discuss again, as they’re not on the slides.

APIs still need a view model

There was a question about the API view of your data vs the database view. A good API still follows MVC principles. Just because a View is written in JSON instead of HTML doesn’t make it a model. Isolate it, because otherwise a database change is an API change. You can use automappers to save you having to write convertors, but always create a view for your API so you can handle versions and create consistency.

There was also a big discussion on how deep the hierarchy should be, particularly relating to data obesity. And it’s a different tradeoff if you’re optimising for poor latency, where larger packets with redundant informatio make more sense, or timeliness where small packets that can be built and parsed quickly are preferred. It all depends on your users. It may be the case, as the Trello API does, that returning the deep hierarchy is a request option so that the user can decide.

User Experience doesn’t always mean asking the user

Developers will ask for lots of things that aren’t useful. Sometimes you need to discover what the user needs are. Maybe it’s a test-first design. Maybe it’s a loosely typed API to help you discover what users want to do (think Google search vs Yahoo’s hierarchy – Google is more loosely types so was more likely to return odd results, but Google had lots of data on what people were searching for that it could learn from).

Link suggestions from the audience

Thanks for these suggestions. I’ll have to try them out myself, so I’m putting them here without warranty.

Kong – to consolidate your APIs, and create the polished surface that doesn’t expose the dirty, inconsistent history behind it.

RAML – to design a typed RESTful API up front so you know what it will look like.

Heroku’s HTTP API design guide

Slides from Google Docs

Developers are users too

Slides from Slideshare

Advertisements

One thought on “Developers are Users Too : Why the User Experience of Your API sucks #yourapisucks

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s