API changes between v0.5 and v0.6
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 https://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.
Additional information from the old page
- Changeset tracking comments and user agents
- 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)!
- Improvements to allow the possibility of HTTPS in the future
- Support for transactional database updates
PUT vs. POST
The following conventions should be used for PUT vs. POST selection:
- PUT shall be used for operations, which can be executed multiple times with same content without changing the result on the database. (tbd.)
- 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 guarantee 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.