PHP Advent Calendar Day 6

06 Dec 2007

Today's entry, provided by Davey Shafik, is entitled APIs, UIs, and Other Underused Acronyms.

Davey Shafik

Davey Shafik
Davey Shafik is an author, speaker, and developer with 10 years of experience in web technologies.
Zephyrhills, Florida

Have you ever used a web site and thought, "How can something suck this much?" Sometimes, the ideas are great, but it just feels clunky. The most common cause is a poor user interface.

User interface design focuses on making things feel natural. A good user interface doesn't require the user to think. Typically, if you need to provide instructions on how to use something, you should instead invest more into the usability of it.

There is something good about the web; if you're faced with a problem, chances are good that someone else has already solved it. Search for sites that have similar requirements, and look at how they do things. Does it work? Does it feel natural? What can you improve?

It's important to understand that advancements in user interfaces must be evolutionary, not revolutionary. Time Machine is an exception to this rule, because it's a user interface for something that never had a good one and was never widely used by the target audience.

If you want to learn good principles of UI design, I highly recommend the book Don't Make Me Think by Steve Krug.

Code has similar needs. It should be usable and natural. The less thinking the better. In this sense, user interface design and API design are both critical to building successful applications. The two are also synergistic; the back-end API should be as simple as possible to support a simple, clean user interface.

Good APIs should be immutable. They should never need to change (additions are fine), and while this is an unrealistic goal, it is something you should strive for. A good API is one where the code behind it can be changed without requiring changes to applications that use it.

For example, you might have a getNewsStories() function that reads stories from an RSS feed and returns them as a nice data structure. As time goes by, you realize that you want to cache the stories, maybe to create archives. Now, you need to start reading from your data store, not just RSS. As long as the returned data structure hasn't changed, none of the code calling getNewsStories() has to change.

Finally, it's important to think about the data being returned from your API. Should you return HTML nuggets? What if you want to start serving your data as a web service? You should have two different sides of your API: data retrieval and rendering. By doing this, you leave yourself open to future modifications, either displaying the same information in a variety of ways within your HTML output, or in entirely new ways, like JSON.

I'll leave you with this rule of thumb. If you had to think hard to come up with the idea for a user interface or API, it's probably too complex. Let usability be your guide.