[OSM-dev] lessons from the api 0.6 discussion

Alexander Holy alex at alexholy.net
Sun May 11 01:19:05 BST 2008


Please let me share a few thoughts about the  API 0.6 discussion I've been
wathing over the last few days.

The discussion makes it pretty obvious there are quite different views and
expectations how things should progress. Mostly, this seems like a
communication problem that deserves to be handled.

There is absolutely nothing wrong with an agile ecosystem and rapid API and
data structure changes. In fact, the keep-it-simple approach together with
rapid small improvements are the reason why OSM is in such a good shape.

However, for people being new to OSM, people just learning about OSM by
reading the Wiki, and people evaluating OSM many things WILL remain unclear.

What is definitely missing is a short manifesto that is prominently linked
on most of the main and API pages. It should clarify a few things, and more
important, set a few expectations and make recommendations. [ NOT just more
FAQ entries ]

Things I'd like to see highlighted:

OSM is all about creating high quality, up to date, free (clarify context of
"free") geo data. It's all about the data.

It should be made very clear to new users and developers what to expect.

E.g., what data structures and APIs are likely to change in the future.
There should be crystal clear information about the likely rhythm of these
changes, and maybe the obvious remark that you should encapsulate the OSM
data/API layer.

There should be a clear remark how this relates to the online server and the
slippy map.

People should understand that the online slippy map is not intended as
direct replacement for things like Google/Yahoo/MSN maps (in terms of
availability, API stability, load factors)

There should be clear and concise recommendations when, if and how you
should create local copies of OSM data and base your service/project/program
on these local copies.

What do you think?


P.S.: Personally, I'd love to see some (sane) self-imposed restrictions on
API changes.
Suggestion: "We will guarantee that all API changes will be fully documented
on the Wiki page xx N weeks before the transition". Personally I believe a
healthy N would be something like 4 weeks.

More information about the dev mailing list