API changes between v0.5 and v0.6

From OpenStreetMap Wiki
Jump to: navigation, search

General information

This change history reflects the changes between API v0.5 and API v0.6.

Version 0.6 was released on 2009-04-20.

Changes to existing functionality

URL

The URL for the API has changed to http://api.openstreetmap.org/api/0.6/

Ways

A limit of 2000 nodes per way has been established.

Relations

Relation members are now ordered and guaranteed to be returned in the same order.

New functionality

Changesets

To make it easier to identify related changes the concept of changesets is introduced. Every modification of the standard OSM elements has to be wrapped in a changeset. A changeset may contain tags just like the other elements. A recommended tag for changesets is the key comment with a short human readable description of the changes being made in that changeset. A new changeset can be opened at any time and a changeset may span multiple API calls. Because of this it has to be closed manually as the server can't know when one changeset ends and another should begin. To avoid stale open changesets a mechanism is implemented to automatically close changesets upon one of the following three conditions:

  • More than 50.000 edits on a single changeset
  • The changeset has been open for more than 24 hours
  • There have been no changes/API calls related to a changeset in 1 hour (i.e. idle timeout)

Changesets are specifically not atomic. Given how many changes might be uploaded in one step it's not feasible. Instead we opted for optimistic (client-side) locking using version numbers (described below). Anything submitted to the server in a single request will be considered atomically, hence the need for diff uploads. Hence you cannot rollback a changeset using the API. Changesets cannot be deleted either.

Version numbers

Every element in the database has a version number which is returned in the XML API responses and included in the planet dumps. This version number is used for optimistic locking. To upload a new version of an element, the client will need to provide the version of the element it is modifying. If the version is not the most recent an error will be returned.

Reliably identifying users

The previous API v0.5 returns the user display name. The user can update this at any time and there is no history stored for display name changes. This means there was no way to reliably identify which user made a specific change. The 0.6 API will include the numeric user ID of the account in addition to the display name. e.g.

<node id="68" ... user="fred" uid="123"/>

This still requires the user to have made their edits public. User id for users who have previously made anonymous changes will not be visible.

With unanimous agreement of the OSMF, anonymous edits will no longer be allowed.

Diff Upload

It is now possible to upload diffs using the OsmChange format.

Information from the old page

  • Support for changesets, including creating and closing, tracking comments and user agents
  • API to return current version number of every object
  • Any object change to contain old version number (optimistic locking) - update fails if version does not match
  • Any object change to contain changeset id
  • The user field moves from the individual objects to the changeset
  • DELETE to get payload as result of above requirements (does not have payload in 0.5)!
  • Support for diff uploads with transactional support
  • Improvements to allow the possibility of HTTPS in the future
  • Support for transactional database updates
  • Relations to become ordered

PUT vs. POST

The following conventions should be used for PUT vs. POST selection:

  1. PUT shall be used for operations, which can be executed multiple times with same content without changing the result on the database. (tbd.)
  2. POST shall be used for operations, which when executed multiple times with the content change the result of the database. E.g. changeset/#id/upload or changeset/#id/expand_bbox (tbd.)

Diff uploads

Currently there are a number of problems relating to sending each change as a new request:

  • It makes support of HTTPS impossibly expensive
  • Cannot guarentee transactionality since a transaction would be open-ended

Hence it was decided to allow client to upload chunks. Everything in a chunk could be supported in a single transaction. And less connections means HTTPS becomes feasible. The different Change file formats we considered, we decided on OsmChange since it seemed closest to what was required. In particular the need for placeholders to allow changes to refer to object created in the same upload.

There will probably be a maximum size to the diffs to prevent a single client holding the server too long. The limit will have to be determined after seeing practical usage. There is also the possibility of truly large changesets to be posted for offline processing.

Todo List

We're ready to go!

TomH has an action plan for various steps which need to take place over the coming weekend. The first steps involve putting the database into read-only mode. Matt will be kicking off various stages of his database migration scripts. Some details of DB changes are described above. So the main TODO item is ...follow the plan!

Some other things:

  • Some Osmosis Postgres compatibility tweaks still to do.
  • Some Planet.osm tweaks still to do.