OpenStreetBugs/API 0.6

This page describes yet another reimplementation of the API of OpenStreetBugs intended to potentially be put onto the main page.

This is currently only a discussion draft and is likely to still change. Please suggest improvements

The API is currently accessible as a test via HTTP with the URL prefix http://openstreetbugs.dev.openstreetmap.org/api/0.6/bugs/. The source code is available in the OSM svn for a more exact reference.

The implementation might not fully conform to these specifications yet.

General conventions

This API intends to be backwards compatible to the old OpenStreetBugs API.

All data is encoded in UTF-8. All coordinates are in WGS-84 (normal GPS coordinates).

You access the API using normal HTTP GET requests on the URL http://openstreetbugs.dev.openstreetmap.org/api/0.6/bugs/<Action>?<Param 1>=<Value 1>&<Param 2>=<Value 2>&<...> (without the <>). (In this document, everything that stands between < and > is to be replaced by the appropriate values.)

Every bug consists of an ID, a position (longitude and latitude), a description, an author, a creation date, a status and zero or more comments consisting of a text, an author and a date. The ID is a 64-bit integer. The status can be open (represented by a 0) or closed (represented by a 1). A closed bug does not differ from an open bug in any way except for its status. Several API methods that return bugs return the text, author and date of the bug and its comments not in separate fields but as one single HTML string. This is for compatibility reasons, and there should also be methods available to get the information in separate fields. If returned in a single textfield, the comments and the main description are separated by the code <hr />. The format how the author and the date are encoded in the description and in the comments is not standardised (see #Suggested improvements).

Reading bugs

getBugs

Returns the existing bugs in the specified bounding box. The bugs will be ordered by the date of their last change, the most recent one will go first. The list of bugs can be returned in several different forms (e.g. as executable JavaScript, XML, RSS, json and GPX) depending on the format parameter.

URL: http://openstreetbugs.schokokeks.org/api/0.1/getBugs?b=<Bottom coordinate>&t=<Top coordinate>&l=<Left coordinate>&r=<Right coordinate> (example)
Return type: text/javascript
Source code: http://github.com/emka/openstreetbugs/blob/master/api/0.1/getBugs

The b,l,r,t parameters should be renamed to a single bbox= parameter to be in line with the rest of the api

The JavaScript function that will be called by this API call has to have the following format (see #General conventions for the format of the single parameters):

function putAJAXMarker(bugId, longitude, latitude, descriptionAndComments, status) { }

searchBugs

It should be possible to search for text in the comments

TODO

getOwnBugs

Retrieve your own bugs and bugs you have commented on.

TODO

getGPX

Should this be merged with the getBugs call with just a different format= parameter?

getRSSfeed

Should this be merged with the getBugs call with just a different format= parameter?

getItem

Returns the data on a specific bug entry

URL: http://openstreetbugs.schokokeks.org/api/0.1/rssitem?id=<Bug ID> (example)
Return type: application/rss+xml
Source code: http://github.com/emka/openstreetbugs/blob/master/api/0.1/rssitem

Editing bugs

addPOIexec

This API function should probably be renamed

Creates a new bug on the specified position. Returns a message as text that indicates whether the bug was successfully created. If the format parameter is used, the output can also be a JavaScript function call.

URL: http://openstreetbugs.schokokeks.org/api/0.1/addPOIexec?lat=<Latitude>&lon=<Longitude>&text=<Bug description with author and date>&format=<Output format>
Return type: text/html (actually plain text) or text/javascript
Source code: http://github.com/emka/openstreetbugs/blob/master/api/0.1/addPOIexec

If format is js, a function like the following will be called:

function osbResponse(errorMessage) {
  if(errorMessage == undefined)
    alert("Bug successfully created.");
  else
    alert("Error creating bug: "+errorMessage);
}

editPOIexec

This API function should probably be renamed

Adds a new comment to an existing bug. Returns a message as text that indicates whether the comment was successfully added. If the format parameter is used, the output can also be a JavaScript function call.

URL: http://openstreetbugs.schokokeks.org/api/0.1/editPOIexec?id=<Bug ID>&text=<Comment with author and date>&format=<Output format>
Return type: text/html (actually plain text) or text/javascript
Source code: http://github.com/emka/openstreetbugs/blob/master/api/0.1/editPOIexec

If format is js, a function like the following will be called:

function osbResponse(errorMessage) {
  if(errorMessage == undefined)
    alert("Comment successfully added.");
  else
    alert("Error adding comment: "+errorMessage);
}

closePOIexec

This API function should probably be renamed

Marks an existing bug as closed. Returns a message as text that indicates whether the bug was successfully closed. If the format parameter is used, the output can also be a JavaScript function call.

URL: http://openstreetbugs.schokokeks.org/api/0.1/closePOIexec?id=<Bug ID>
Return type: text/html (actually plain text) or text/javascript
Source code: http://github.com/emka/openstreetbugs/blob/master/api/0.1/closePOIexec

If format is js, a function like the following will be called:

function osbResponse(errorMessage) {
  if(errorMessage == undefined)
    alert("Bug successfully closed.");
  else
    alert("Error closing comment: "+errorMessage);
}

API - style

Retrieving bug data by bounding box: GET /api/0.6/bugs

Returns the existing bugs in the specified bounding box. The bugs will be ordered by the date of their last change, the most recent one will go first. The list of bugs can be returned in several different forms (e.g. as executable JavaScript, XML, RSS, json and GPX) depending on the format parameter.

URL: http://openstreetbugs.dev.openstreetmap.org/api/0.6/bugs?bbox=left,bottom,right,top (example)
Return type: text/javascript TODO

Error codes

HTTP status code 400 (Bad Request)

When any of the limits are crossed

Read: GET /api/0.6/bug/#id

Returns the existing bug with the given ID. The output can be in several formats (e.g. as executable JavaScript, XML, RSS, json and GPX) depending on the format parameter.

URL: http://openstreetbugs.dev.openstreetmap.org/api/0.6/bug/#id ([1])
Return type: text/javascript TODO

Error codes

HTTP status code 404 (Not Found)

When no bug with the given id could be found

Create a new bug: Create: POST /api/0.6/bug/create

Create a new bug

URL: http://openstreetbugs.dev.openstreetmap.org/api/0.6/bug/create?lat=51.00&lon=0.1&name=NoName&text=ThisIsABug (example)
Return type: text/javascript TODO

Error codes

HTTP status code 400 (Bad Request)

if the text field was not present

HTTP status code 405 (Method Not Allowed)

If the request is not a HTTP POST request

Create a new comment: Create: POST /api/0.6/bug/#id/comment

Add a new comment to bug #id

URL: http://openstreetbugs.dev.openstreetmap.org/api/0.6/bug/#id/create?name=NoName&text=ThisIsABugComment (example)
Return type: text/javascript TODO

Error codes

HTTP status code 400 (Bad Request)

if the text field was not present

HTTP status code 404 (Not found)

if no bug with that id is not available

HTTP status code 405 (Method Not Allowed)

If the request is not a HTTP POST request

Close: PUT /api/0.6/bug/#id/close

Close a bug as fixed.

URL: http://openstreetbugs.dev.openstreetmap.org/api/0.6/bug/#id/close (example)
Return type: text/javascript TODO

Error codes

HTTP status code 404 (Not Found)

When no bug with the given id could be found

HTTP status code 405 (Method Not Allowed)

If the request is not a HTTP PUT request

Search for bugs on text and comments: GET /api/0.6/bugs/search

Returns the existing bugs matching either the bug text or any of the comments to the search query. The bugs will be ordered by the date of their last change, the most recent one will go first. The list of bugs can be returned in several different forms (e.g. as executable JavaScript, XML, RSS, json and GPX) depending on the format parameter.

URL: http://openstreetbugs.dev.openstreetmap.org/api/0.6/bugs/search?q=SearchTerm ([2])
Return type: text/javascript TODO

Error codes

HTTP status code 400 (Bad Request)

When any of the limits are crossed

Suggested improvements

Feel free to add something here or on the talk page.

• General: Introduce a better data format that separately stores comments, descriptions, authors and dates.

  done

• getBugs: Bounding boxes cannot cross the date line as the l parameter has to be less than the r parameter.
• rssitem: Should contain all changes of the bug instead of just the last one.
• addPOIexec/editPOIexec/closePOIexec: Should not define MIME type text/html without actually sending HTML code.

  done

• addPOIexec/editPOIexec/closePOIexec: Include a mechanism in the callback JavaScript function to find out which action actually failed. Perhaps make an additional parameter that the client may specify and that will then be sent back through the callback function?