Thor Mitchell, a developer evangelist at Google, gave a presentation at APIWorld this September 2014. His talked focused on the product decisions that API providers face when providing an external-facing API. He organized the decision points into 3 phases: starting an API, running a live API, and closing an API. I’m summarizing the talk based on what I learnt (i.e., not exactly what he said).
Starting an API
Starting an API is equivalent to launching a new product. The product has to satisfy a customer’s needs, which in this case is the developer using the API. Customers should be included in the design phase to make sure their needs are addressed.
Second, the API should be well documented. Documentation can be generated from API design tools such as Blueprint, Swagger, and RAML. The product roadmap of an API may also include launching associated dashboards and debugging tools.
Third, a terms of service (TOS) and service level agreement (SLA) should be defined when launching an API. TOS defines what customers can and cannot do with the services provided by the API. For example, saving a user’s information from the API in an external database might be disallowed. A SLA defines the API’s intended uptime, communication policy between provider and developer, and deprecation policy among other things.
Live API
When the API is live, it should be revised without breaking backward compatibility. As long as backward compatibility is maintained, the new features can be documented in release notes. The provider shouldn’t have to change its version number.
Different customers will use the API for different purposes. The way each customer uses an API, the order and sequence of API calls, allows the provider to distinguish between different customers. If it becomes evident that a customer is not following the terms of service, it may be come tempting for providers to block the misbehaved customer. These methods to block misbehaved customers will also adversely affect well-behaved customers from using the API. Instead of blocking a few customers, time and effort should be focused on making the API better.
Closing an API
An API may not meet customer needs and require changes, like all other software. If the API is no longer useful to majority of customers and becomes too costly to maintain, a provider may also choose to deprecate the API. The provider should give advance notice that an API is being deprecated and indicate a grace period before turning off in the SLA. This gives developers enough time to update their software. Regardless, customers might write negative comments on forums, but providers trying to actively block their frustrations is poor taste.
Conclusion
In summary, APIs should be designed with customers in mind and provided as any other product with a TOS and SLA. I haven’t seen his talked posted online, but when it does, I’ll link you to his website.