Clay Loveless: Understanding API Usage

I was in a Point-of-View session at Defrag with Laura Merling of Alcatel-Lucent, Brian Mulloy of Apigee, and Clay Loveless of Mashery. Laura and Brian gave interesting talks, but since they went before me, I was too occupied to take notes. I did take notes for Clay’s talk, however, since he went after me.

Clay gave six tips for making an API work:

Sponsor

Guest author Phil Windley is the founder and CTO of Kynetx, an early stage company providing context automation services. He is also an adjunct professor of Computer Science at Brigham Young University where he teaches courses on reputation, digital identity, large-scale system design, and programming languages.
Phil writes the popular Technometria blog and is a frequent contributor to various technical publications. He is also the author of the book Digital Identity from O’Reilly Media.

Test it all. Unit tests are just the beginning, but if you don’t have them yet, don’t start there. Instead, test what your user’s experience with end-to-end black box tests. Replaying your access logs is a good way to go since you’ll then get tests that mock-up what your users actually do rather than what assumptions you’ve made. Last thing on testing: validate your return payloads. Getting a response isn’t enough since a stack trace isn’t the same as getting valid XML, JSON, or what have you.
Plan for the future. Use versions on your APIs. This allows you to avoid forklift upgrades that you have to coordinate with all your users. Versions aren’t sexy or semantic, but you have to do it anyway. Announce versions well in advance to avoid surprising users.
Embrace standards when practical. APIs are better when they’re predictable. Standard approaches make tooling and monitoring easier. It’s easier to monitor anomalies on non-unique snowflakes. Standards help avoid uncomfortable migrations like the OAutholypse. Standards also enhance runtime validation by allowing you to reject bogus calls earlier in the request pipeline.
Monitor everything and be honest. Testing is vital to this effort – you should know before your users. Trends are your friends. To spot trends, you need to be continuously monitoring. Fess up fast – no user wants to think they’re your early warning team. Be open by default. Make it part of your nature.
Fail well. Well-formed errors win friends. Developers will be more tolerant of failure if you anticipate the possibility and are prepared. Make failures obvious so that monitoring is easy. Try to localize failures so that any given failure doesn’t screw everyone. Take care of you big customers.
Use a management system. Obviously this is a plug for Mashery, but that doesn’t make it wrong. Active monitoring by a service with a support team can be your early warning system. Analytics can help understand how your API is used.

My own talk was about how using events will make users happy. The idea is that client-server architectures require users to “go and get” whereas an event-based architecture lets goodness flow to users without their continual interaction. Web 2.0 was largely about dynamic queries against static data pools whereas the future web will include rivers of information with static queries. My contention is that we need new abstractions for processing these rivers of information. That, of course, leads us to KRL (Kynetx Rule Language) and the event processing layer that Kynetx is building for the Web.

Discuss