Good Practice for Provision of APIs
April 15th, 2009 — Marieke GuyDeveloping and provision of APIs can be like most other forms of software development and many of the best practice techniques are well established. However the API process, and here we are possibly referring mainly to Web APIs, is also dissimilar from other forms of development because of the unpredictable nature of APIS. This may mean that the users and use of an API are unknown. To achieve the goal of well-written and released API developers will do well to consider the entire API lifecycle from conception onwards. Best practice can cover areas from the basics aimed at getting more people using APIs, to general ‘etiquette’ for API consumers aimed at easing relationships with API providers.
- 1.1 Plan
- 1.2 Gather Requirements
- 1.3 Make it Useful
- 1.4 Keep it Simple
- 1.5 Make it Modular
- 1.6 Follow Standards
- 1.7 Use Consistent Naming Structures
- 1.8 Make it Easy to Access
- 1.9 Let Developers Know it Exists
- 1.10 Version Control
- 1.11 Provide Documentation
- 1.12 Error Handling
- 1.13 Provide it in Different Languages
- 1.14 Make Sure it Works
- 1.15 Feedback
- 1.16 Maintain your API
April 15th, 2009 at 10:17 am
[...] Good Practice for Provision of APIs [...]
May 12th, 2009 at 2:53 pm
Brief comments… (sorry)
The treatment of REST here seems far too minimal but given your current structure I’m not sure where it would go.
Ditto any thinking about access control / identity in 1.8. The reference to Linked Data in 1.8 seems out of place (though treatment Linked Data and REST should probably be co-located).
May 18th, 2009 at 11:05 am
I think the point about “the unpredictable nature of APIS” really needs a lot of qualification; especially if the report is saying it applies “mainly to Web APIs”.
One of the key tenets of the REST architectural style, the set of principles which was used to guide the development of foundational Web standards like the URI syntax and the HTTP protocol, is that of the “uniform interface”; i.e. that components within the system expose the same interface, rather than components within different subsystems exposing different interfaces. I don’t see how this fits with a notion that APIs are “unpredictable”.
I think this particular point is a symptom of a the more general point that the report probably needs some discussion of the different contexts within which “APIs” are designed and deployed, and the different “affordances” of those different contexts. What is “good” in one context isn’t necessarily “good” in another.
The globally distributed, highly devolved context of the Web is a very different different context from that of, say, the systems of one particular organisation. And so application interfaces within those two different contexts may have very different requirements and characteristics. The foundational standards of the Web were designed to support the requirements of that particular context, and they exhibit certain properties and characteristics specifically to meet the particular requirements of that context.
Without this sort of differentiation, it seems to me it is very difficult to make particular recommendations about what constitutes a “good” API.
May 18th, 2009 at 2:49 pm
Hi Pete,
There is something in the main report that talks about types of APIs:
“Although some have found it useful to make a distinction between traditional and Web type of API for this report some better distinctions might include:
• projects which provide an API versus projects which are actually developing a Standard API (e.g. OpenDOAR offers an API, SWORD is a project defining one).
• APIs which are about offering simple access to resources (e.g. RESTful) versus ones which are about exploiting some re-usable function (e.g. APIs for workflow systems)
• APIs which are tied to programming languages versus those which are not (SOAP/ HTTP REST/XML RPC)
We’ll have a go at expanding on this to differentiate further.
Thanks
Marieke