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 SmartLogicwe 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
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:
- 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.
- 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.
Check out our other articles on API:
API Planning and Proceeding: Tell Me What You're Working With
API Versioning: 3 Ways to Architect Your API to Handle Versioned Requests
API Development: Turning Controller Actions Into Services
Guide to Application Development Infrastructure: Pairing and CI Servers
