No matter how beautiful and well-designed your new web API is, unless it is well supported, you may find that you become a victim of your own success. Below are 4 suggested key elements of a supportable web API, based on my experiences at
IG.
1. Documentation, documentation, documentation!
Unless it is easier to refer to your API documentation than to contact you, you will be contacted. Don't assume anything is obvious. Document your API in detail. Define your business terms. Explain common interaction patterns. Provide client code snippets and working samples in a variety of language bindings. Provide a FAQ.
Consider providing a client SDK (Yes,I know REST is meant to be easy, but the reality is that unless your client is already a developer, they will struggle. Make it easy for them to use your API.)
Consider providing a moderated forum to allow clients to answer each other's questions. Provide an interactive API explorer allowing clients to try out APIs and see the raw HTTP requests and responses.
2. First and Second Line Support
Provide a "contact us" form instead of direct phone numbers. The page should encourage clients to refer to API documentation, FAQ, and forum (if one exists).
Provide first line, "customer sensitive" support to answer common queries, or at least to ensure queries are well formulated before passing onto second line support. If your organisation already has a customer services help desk, use them! They may balk initially at the perceived technical nature of the support, but should be helped past this by through training and provided access to simple debugging tools, e.g. the API explorer or a facility to search service log files.
Provide dedicated second line support via a rota consisting of the developers who built the API.
Maintain a searchable log of frequently answered questions (and answers). Update the public FAQ from this log.
3. Effective error handling
Give API clients as much error information as possible in request responses. If inputs are incorrect - tell them why. If error codes are used - ensure these are documented.
Log every request in detail, including request authentication headers and body (subject to client privacy constraints). Use a transaction id pattern to allow the flow of API requests to be tracked across multiple back-end systems. Provide easy access to system logs, e.g. via
Splunk, which provides a searchable index over a number of configured log files. Splunk additionally allows requests to be charted and management dashboards to be created. Senior management will want to know just how popular the API is.
4. Provide a barrier to entry
If, despite all of the above, the demand for your API is still overwhelming, consider:
- throttling your API, with chargeable tiers for increased quotas
- requiring that a verified account to be opened before an API can be used
- providing support to valued customers only (or on a subscription basis).
