So you want a Public Web API?

So you'd like your customers to integrate with you, and what better way to do this than a shiny new public web API? Perhaps, like IG, you had a suite of existing web services for your web and mobile platforms, so it's simply a matter of "exposing" these, right?

But is your existing API good enough to expose as is? What exactly makes for a good public API?

Applicability

Does the API meet yo​ur customers' needs?

This may seem an obvious point, but very often public APIs, particularly if derived from existing APIs, expose what the company does, not what the customer needs. An example of this is the IG EPIC instrument identifier. Used internally to identify instruments (markets), these are proprietary to IG and difficult for customers to relate to real-world identifiers (RIC, SEDOL and the like).

Does the API meet your busi​​ness goals?

"Build it and they will come" is certainly one approach to justifying building an API, but what if the wrong people come, the time-wasters, those who will consume all your support and development bandwidth without offering any real value to your business - often at the expense of the serious customers who will bring real revenue? Does it even make more sense to offer your API to individuals, as opposed to institutions?

Similarly the cost model of the API needs to be defined. Is it free or restricted, should there be price bands, should cost be related to type of usage? How will you enforce this? Having a clear and understanding of the API business model (supported by detailed API usage metrics) is critical to the success of the venture.

Consistency

A consistent API looks and behaves in a predictable manner. This involves deciding on a fundamental access protocol (e.g. REST and Lightstreamer), and layering above that standard conventions: a functional model (consistent URI scheme, resource types, attribute names, types, …), and a non-functional model (versioning, error handling, security, retry handling …)

Availability

An available API has well-defined and monitored SLAs, is resilient to failure, scalable, versioned, repeatedly tested so that API interface or downstream changes do not impact customers, secure and audited (both for the API's sake, but also for the customer's.)

Usability

A usable API is thoroughly, accurately and consistently documented, both in terms of an API reference, but also in terms of Getting Started and User Guides to introduce clients to non-trivial aspects of using the API. This is where API consistency helps immensely.

Consider implementing a portal for customers to easily access API documentation, as well as to try out APIs interactively. Offer support contact details and a forum to allow customers to interact with your company, but also to build up a community offering mutual support. Decide what your internal customer support team structures will look like. Consider setting up a customer-facing technical team with ready access to a team of internal API developers.

Good public APIs do not just magically appear overnight - they are complex and costly to build well. Are you sure you want one?

About the author:

Robert Morschel works as an enterprise architect at IG, and has more years of software industry experience than he cares to disclose. He blogs at SOA Probe and The Oddest Box. Find him on LinkedIn.