API v0.6 (Archive)
From OpenStreetMap Wiki
This page contains some bits left over from the time while API 0.6 was still work-in-progress.
Contents |
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 2000 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 http://www.openstreetmap.org/api/capabilities use this if you need to use these limits in your code.
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 Servers/smaug over the migration weekend, go look at the lovely code now available in subversion here: http://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 Servers/smaug
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 |
