Memo to API Service Providers

This is a followup and expansion to a blog entry I wrote in October 2007, titled "Memo to OAuth Service Providers".

Recently, I've been working with a host of companies with open APIs built specifically for 3rd parties to build on. Call them mashups companies, platform companies, or just plain old smart companies. But if you are contemplating creating an API for your new online service, I have some suggestions on making your API offerings a success. 

Use Building Blocks
If at all possible, don't invent a new protocol, don't invent new formats, and don't even invent a new API, if you can avoid it. There any number of building blocks out there such as OpenID, OAuth, HTTP (REST especially) and Atom upon which you can compose a set of interactions to fulfill a wide variety of needs. This isn't to say that your API demands unique components, but the thing to remember is that the service offering behind your API, not the mechanics of the API itself, should distinguish your API offering from others. 

Think of the API as a Separate Product You Are Delivering
It really is a separate product. Its your company's service packaged as a product for delivery to a new set of customers (other developers) with a new intent (letting third parties make your business successful and creating an ecosystem in which you are cemented as a core participant). Along these lines, there are several key things to keep in mind:

• The API isn't delivered until your side (the provider) conforms to a publicly published specification. This seems so obvious stated this way, but like other product launches, its all to easy to make "vaporware" claims about APIs - declaring you have delivered more than what is actually there.
• You may even want to go so far as to build tests for your API first, before you build a server-side implementation. Build a proof of concept client application that exercises all the functionality in the API. When that POC works, your API is complete!

Your API User are Your Customers and Partners.
As I mentioned in Memo to OAuth Service Providers", the mindset you should have is that the users of your API are your customers as well your partners. This is especially true if you are entirely or largely a platform company with little or no direct contact with end users. Your API customers are likely going to bring you business development leads. They are your best sales team -if you're lucky, maybe they are your only sales team! Think of them and care for them like you would any other service user: understand their needs, maintain bidirectional communication channels and respect their sensitivity to quality (uptime, performance, etc).

Make Life for Your Developer Users EASY
This is probably the most important message I have to deliver. To these nice folks (many of whom are just like you and may even themselves be providing services behind APIs), you are often one of several options and you need to make their lives easier than it is today, not harder. Here are a number of concrete steps you can take, some of which I've seen implemented, some of which I think may be novel:

• Document the service and not just the API. Start at 50,000 feet and work your way down. Nothing frustrates me more as an API user to get API documentation that starts with API methods and fields, without bothering to tell me what they do. So many times, API providers forget to describe to me what the service behind the API does - it is often the most critical thing for an API client to understand. After all, an API customer is typically not writing to the network level specification, but rather they are orchestrating interactions with your service via calls to a API client library.
• Provide open source client API libraries in all the major languages your users are likely to implement in. This one is obvious, but its a prerequisite for success these days.
• Provide a reference client application to demonstrate usage of the API. Again, another obvious one. Make sure its well documented, and reflects any updates in the API over time. Consider the reference client part of the deliverable package when you update the API.
• Make an instance of your service available for developers in a sandbox, if at all possible. Developers will do stupid things and need to hit your API to learn. Don't make them feel guilty for doing it, or punish them for messing up. Encourage them. Make it easy. Allow them to make mistakes in the privacy of a development sandbox, if at all possible.
• Don't neglect error reporting, and think of it as an educational tool for the API client developer. People developing server sides of APIs often think that the appropriate solution for reporting errors is to be cryptic and expect folks to refer to specifications to understand what has happened. There's generally no reason for this sort of torture. Especially when a client developer has no insight into the server environment, its nice to give them some extra information about what's going wrong. Unless you have a buggy server implementation, its usually a problem on the client side - and more often than not its a bug in comprehension of how your API is supposed to be used. Use failures and exceptions as learning moments.
• Build mechanisms to give client developers extra debugging information during development. Perhaps you can provide an internal log of how an API call is being processed and the steps inside your implementation, at some general level of detail. This could be controversial (some API client developers may claim your system is not doing the right thing if they have too much insight). However, it can help them understand how the system is actually working when things are going right, so they can see why things are going wrong when they are going wrong. Also, we know that abstractions are leaky (an API is one sort of abstraction) so giving client developers a peek under the covers of the API implementation on the server side may occasionally be helpful in discovering when those leaky abstractions are causing them problems.
• Build a way for developers to reset your service to a known state for development and debugging. There's really nothing more frustrating than trying to create tests or track down bugs that only occur when the API being accessed is in a certain (sometimes unknown) state. In many cases, it could be very helpful for a client developer to "push a button" to set the server side to some known state (e.g. empty out a database, populate a database with a known set of data, etc). This also helps greatly with the next bullet point.
• Think about your client developers' testing issues. Think about their testability problems and how you might be able to help them, or at least not create extra problems. This is especially true with a test-first development approach that is advocated in some agile development methodologies. This sort of testability may mean providing a client API with a test harness built in (e.g. Mock Objects to stub out the actual service API). Or, it could mean the sort of "known-state setting" that I mentioned in the last bullet point, so that even unit testing of the client software can happen against the live (development) API you are providing. 

Eat Your Own Dogfood
This is more than just building a proof of concept. I actually advocate building a live application that accesses your API as would any other client. This is so that you can feel the pain (and experience the joy) of your API client customers. If you are good, you'll be able to anticipate what your customers want and need before they even know it.

Monitor Usage of Your API
Like any other online service, you really need to know, at a technical level, what's going on with your API service as it is getting used. Know your usage patterns - they are almost certainly going to be different than what you first guess. Knowing your service helps you maintain uptime, predict scalability issues, and be able to avoid issues that will keep your customers from being happy. You will be able to predict future growth and plan for investments in the API offering. Finally, monitoring usage will also help you in the area of security, because monitoring helps establish baseline usage volumes and patterns that can be used to detect security or other anomalies.

Build a Community of Developer Customers
If you launch an API and have developers building to it, you already have a community. Recognize it, support it, and realize that they are likely investing a lot of time and exposing themselves to a certain amount of business risk by relying on your API. Give them reasons to continue the partnership and feel that the risk is well understood (if not completely managed). Let them know who you are as a company, and the sorts of investments and commitments you are making in this API, and acknowledge the fact that this is a symbiosis. There is no such thing as a service provider if there isn't a service consumer.

And here's one more thing about the community. Call it the Wachob corrollary to Selfridge's law: "The API Customer is Always Right". Thats not literally true, of course, but it is the mentality you need to have, especially when you are just launching. This is a make or break time - either your API users like what you have, or they will quickly walk away. You are serving the API users, not the other way around (unless you are special or have some abnormal market power). You aren't doing them a favor by providing the API - they are doing you a favor by embedding your service in their offering. Recognize.

Don't Forget the Legal Stuff
Your lawyers will surely tell you this, but let me save you 15 minutes of your lawyers time (spent lecturing you). Protect yourself. Think about disclaimers (esp with respect to warranties and service level agreements). If you want to offer those things, think about how you are exposing yourself and how you can cover the risk cost. Think about other legal issues such as copyright (and the DMCA), privacy laws, or other oddball legal issues that your customers may drag you into (online gambling?).

But also look at your legal agreements as an opportunity to express, in a positive way, commitments to your API customers that signal your appreciation of them as part of the ecosystem. One of my favorite signaling mechanisms, built into legal agreements for user-created content service offerings, is explicit language preserving intellectual property ownership on the part of the user for all content they upload/contribute/share through the service. Also, strongly worded privacy commitments, though they may raise the hackles of many lawyers, are also a great way to indicate your intentions towards your API users.

Make it Fun, Make it Personal
Lastly, I think you need to make developing against your API fun and personal. Try to enable "The Thrill of the Hack". Be real, be available, be a company of people, not a company behind a API call. Do this and everything above and you'll have the best odds for developing the fanatical userbase your service API so richly deserves... 

Want Some Help on This?
Glad you asked. I'm available to consult to any company that would like help on the issues described in this blog post. I can be reached at gwachob@wachob.com

Comments

[Brandon Watts]

These are great tips, Gabe! We appreciate the memo. :)

Brandon Watts
Daylife Evangelist

[Ran Arad]

Interesting post. I myself designed quite a few APIs, and found some new ideas here. I wrote a blog post on the subject, with a more nuts-and-bolts approach to designing an API - the actual low level concepts of it:
http://blog.radvision.com/codeofcontact/2008/02/04/can-have-it-all-flexability-with-simplicity/

[ScottERICKA26]

I received my first business loans when I was not very old and that aided my family very much. Nevertheless, I require the collateral loan once again.