Re: APIs Design patterns

Hi Marcin, Dom,

On Nov 19, 2009, at 09:34 , Dominique Hazael-Massieux wrote:
> • I think the most useful thing the document should do is to record API
> design issues that have arisen in WebApps, Geolocation and DAP (see
> below for some examples), and document the outcome of the discussions
> (with a clear guidance when there is one, or simply with cons and pros
> when the outcome is not a clear cut)

Right, the fact is that we have to fit in an already rather large body of APIs, some of which are good, some of which are bad and rejected, and yet some more are considered bad but kept because sometimes the cost of making a bad idea go away is higher than that of living with it.

> • as a result, I would stay away from using RFC2119 keywords as much as
> possible

Much agreed. For me the greatest value in documenting patterns is so that we don't have to explain everything again every time someone new joins the WG. Equally, none of these rules are set in stone — in following the priority order "users over authors over implementors over specifiers over theoretical purity" adherence to patterns comes at the end, so giving the impression that they may be normative is misleading.

Some of these items will probably not be possible. For instance "All APIs must follow the same convention when handling callback functions" won't really be possible as depending on the use cases callbacks or events make more sense. I take this as an example of a case where trying to create universal patterns won't work. That's why I think that this document would be best written as a set of Best Practices (like MWBP for instance), it's all about "shoulds" and trade-offs.

--
Robin Berjon
  robineko — hired gun, higher standards
  http://robineko.com/

Received on Thursday, 19 November 2009 09:56:42 UTC