SmartLogic Logo (443) 451-3001

The SmartLogic Blog

SmartLogic is a web and mobile product development studio based in Baltimore. Contact us for help building your product or visit our website to learn more about what we do.

What Makes a Good API?

July 31st, 2012 by

A good API is a perfect housemate. It helps make sure everything runs smoothly, communicates openly, doesn’t leave dirty dishes in the sink, and most importantly, goes unnoticed most of the time. Everyone works together seamlessly.

On the other hand, a bad API is an awful housemate, and will cost you a lot more than some sleep and your security deposit.

To overextend this metaphor, at SmartLogic we design good housemates and fix bad ones. In doing that, we’ve identified the characteristics a good API has that a bad one doesn’t.

Read on to learn which types of APIs you’ll want moving in, which ones can be fixed, and which ones need to find a new practice space for their baritone saxophone quintet. Too personal?

Consistency, whether Macro or Micro

Jamie Foxx's album is Unpredictable. Not a good API.Unpredictability is only a blessing in the bedroom and Jamie Foxx albums or both at the same time. Your API should be consistent in many different ways, but basically, we can break it down to Micro and Macro consistency:

  1. Macro Consistency: It’s easier for developers to use your API if it’s similar to others out there. Follow standards and best practices, and help developers get what they expect when they integrate the API across different web services, applications, and clients. This may mean stripping them down a bit to broaden their applicability.
  2. Micro Consistency: As with any good code, your API should be developed with consistent results for each aspect in mind. Consistency between all aspects of the API affords abstraction in your API clients’ codebases. Through this abstraction, developers can focus on building useful features instead of studying documentation (which you can build using our rspec_api_documentation gem). For example, GitHub uses the HTTP Link header to present pagination controls, whether you requested comments on a pull request or the commit history for your project.

A consistent API is an API that developers love. Developers loving and using your API should be the ultimate goal.

Make it standard, just not too standard

It’s a fine line. You want to be aware of the standard best practices for API’s without obsessing over them. Without them, we wouldn’t be able to design versatile API’s that work across a variety of different platforms. But a willingness to bend those standards often results in next generation services and a richer set of applications for the user.

Don’t Fall Prey to the Buzz
There’s a lot of buzz about APIs that can do this and that. But think carefully before you build a feature into your API. Will anyone use it? Does it help automate an important task? Again, you don’t want a housemate who holds baritone saxophone quintet in your house.

Perfect is the Enemy of the Good

It’s easy to get caught up in the idealism of the perfect API, but what you’re really after is an API that works. You’re successful if people like using your API and it gives them what they need. Beyond that, don’t get your POSIX in a twist.

What inconsistencies have you found in API’s you’ve worked on? Any API’s that have been particularly good housemates? Join the conversation and leave a comment.

For more like this, follow @smartlogic on Twitter or like us on Facebook.

Image Source

Yair Flicker is the President of SmartLogic.

Yair Flicker's posts