API v0.6 (Archive)

From OpenStreetMap Wiki
Jump to navigation Jump to search

This page contains some bits left over from the time while API 0.6 was still work-in-progress.

Overview of agreed/implemented changes

New limits

API 0.6 introduced the following limits to the API, because of practical reasons:

  • a way shall not list more than 2,000 nodes.
  • a changeset shall not consist of more than 50,000 changes (Should be clarified here: May a single change occur within a changeset multiple times?)
  • the storage of node tags is being harmonised with that of way and relation tags, which means imposing a 255 character limit on keys and values. This means that 578 nodes have had tags truncated to fit. The full archive of these nodes from the 0.5 API is here. Most of these are errors, or automatically added tags, but some will contain useful content and should be manually inspected and updated after 0.6 goes live.

These limits are all documented in the API at www.openstreetmap.org/api/capabilities, use this if you need to use these limits in your code.

Changes in related software

Version information added to planet dump

The planet dump now includes a version="<number>" field for each object in the planet dump, e.g.

<node ... version="123" .../>

The changeset ID is also included, e.g:

<node ... changeset="123" .../>

Database improvements

To understand what's really happening on server smaug over the migration weekend, go look at the lovely code now available in subversion here: https://svn.openstreetmap.org/applications/utils/misc/api06_migrate/ (read the README first)

Approximately as an outline idea, it might be making these kinds of changes:

  • We are moving to PostGres from MySQL. See The Rails Port#PostgreSQL setup (Note: The alternative in MySQL would have been to move all important tables to innodb to support transactionality. The fulltext indexes would be dropped to accommodate this. For the time being both MySQL and Postgres are supported)
  • Adding changeset and changeset_tags tables
  • In the element tables the 'user_id' field will be removed, and replaced by 'changeset_id'
  • The nodes table will get a version number and the tags will be split into a separate node_tags table (consistent with ways and relations)
  • We have created a unique index on the combination of object id and tag key (and version for the history tables), so that it will no longer be possible to have multiple identically named tags on the same object. This was possible until 0.5, but was found to be very rarely used within the data.
  • The "relation_members" table will receive an additional sequence_number column used for sorting the elements. Having the same member in the same relation twice will be allowed. The sequence_number column will not be exposed anywhere, it will just be used to store the sequence in which relation members where uploaded and to return them in the same sequence.
  • Relation members now have a type of 'Way', 'Node' or 'Relation' (previously 'way', 'node' or 'relation'). This change should only affect the database, and doesn't cover the transport of the data in any of the XML.
  • We will perform "changeset synthesis" to retroactively place all past versions of elements into changesets
    • The most basic approach would be to simply lump edits into a single changeset per user.
    • Better would be to create many changesets for a user based on time, simulating the API rules as if the data had in the past been entered via the new API, i.e. changesets do not appear to have stayed open longer than an hour with no activity, or to have stayed open longer than 24 hours.
    • created_by tags can be moved up into these retro changesets
    • Likewise for some other editing meta-information e.g. various TIGER fields
    • Comments could be synthesised to describe what a user did, but that's getting too fiddly and...
The plan is to achieve basic synthesis, hopefully with time-based splitting. Enhancements to historical changeset data can actually be applied gradually as long-running db operations after the 0.6 roll-out.

We'll also be moving to the brand new smaug server.

Status

This section contains the current status of the API calls. Each possible method should be listed, along with a very short description and whether the call is currently implemented, tested, etc...

Method Route Behaviour Status
GET capabilities Returns server capabilities. Coded, Tested
GET node/#id Returns the XML for that node. Coded, Tested
PUT (?) node/#id Updates the node, returns new version number. Coded, Tested
DELETE node/#id Deletes the node, returns new version number(?). Coded, Tested
PUT node/create Creates the node, returns new node number (new nodes always version=1?). Coded, Tested
GET node/#id/history Returns all versions of the node. Coded, Tested
GET node/#id/#version Returns the XML for that version of the node. Coded, Tested
GET node/#id/ways Returns the XML for all ways that this node is part of. Coded, Tested
GET node/#id/relations Returns the XML for all relations that this node is part of. Coded, Tested
GET nodes?nodes=#id,#id,... Returns the XML for all given node numbers. Coded
GET way/#id Returns the XML for that way. Coded, Tested
PUT (?) way/#id Updates the way, returns new version number. Coded
DELETE way/#id Deletes the node, returns new version number(?). Coded, Tested
PUT way/create Creates the way, returns new way number (new ways always version=1?). Coded, Tested
GET way/#id/history Returns all versions of the way. Coded, Tested
GET way/#id/#version Returns the XML for that version of the way. Coded, Tested
GET way/#id/relations Returns the XML of all relations that this way is part of. Coded, Tested
GET way/#id/full Returns XML of a way and all its nodes. Coded, Tested
GET ways?ways=#id,#id,... Returns XML of all numbered ways. Coded
GET relation/#id Returns the XML for that relation. Coded, Tested
PUT (?) relation/#id Updates the relation, returns new version number. Coded
DELETE relation/#id Deletes the relation, returns new version number(?). Coded, Tested
PUT relation/create Creates the relation, returns new relation number (always version=1?). Coded
GET relation/#id/history Returns all versions of the relation. Coded
GET relation/#id/#version Returns the XML for that version of the relation. Coded
GET relation/#id/relations Returns all relations that this relation appears in. Coded, Tested
GET relation/#id/full Returns all ways and nodes in this relation and relations directly members of this relation. Coded
GET relations?relations=#id,#id,... Returns the numbered relations. Coded
GET changeset/#id Returns the XML for that changeset. Coded, Tested
PUT changeset/#id Updates the changeset. Coded, Tested
PUT changeset/create Creates the changeset, returns new changeset number (version=1?). Coded, Tested
PUT (?) changeset/#id/close Marks a changeset closed, returns status only. Coded, Tested
POST changeset/#id/upload Uploads a diff into a changeset transactionally. Returns XML with the committed versions and IDs of the diff elements. Coded, Tested
GET changeset/#id/download Downloads all the changed elements in a changeset in OsmChange format. Coded, Tested
POST changeset/#id/expand_bbox Inserts a point into the bounding box of a changeset. Coded, Tested
GET changesets Queries changesets on bounding box, user or time range. Coded, Tested
GET map Gets all the way, nodes and relations inside a bounding box Coded (Testing started, though some tests have unexpected output)
GET trackpoints Gets paginated trackpoints within a bounding box. Coded
GET changes Returns all changes within a given time period. Coded