Paul’s Blog

A blog without a good name

“Make the Website Use the API” GSOC Project

I’m a potential mentor for the Google Summer of Code project. The goal of this project is to change the website to rely on API calls instead of website-only database queries. It’s focused on the “browse” pages for each object, and might need additions to the API to fully reproduce the functionality. Because I get asked a lot, this is a blog post on what I’d suggest doing if you’re a student interested in the project.

1. Know Ruby and JavaScript

The website code is mainly in Ruby on Rails, and you need to know this before starting the project. JavaScript is a good idea, as one implementation route requires client-side JavaScript changes.

2. Map a bit

It may seem odd for the first step of a coding project to have nothing to do with coding, but it’s essential. You need to learn about OSM’s data model, architecture, and what it’s used for, and the fastest way to do this is with by mapping. You’ll also be looking at how editing software interacts with the API. It doesn’t matter too much what you map, but I’d suggest around your university, a past job, or some other area you’re familiar with.

3. Read Matt’s background post

Matt Amos wrote a blog post on API changes which puts this project into a wider context. Most of the work there isn’t part of the GSOC project, but it helps understand why we want to do this project.

4. Read the API documentation

The API documentation covers all of the API calls, but the ones that are particularly important for the project are the read calls for elements, full versions for ways and relations, ways for node call, relations for element, read and download calls for changesets, and read note call.

The map call, and changeset model are also important concepts to understand.

5. Use JOSM with the console open

Start JOSM with a console window open, and will show all the API calls it makes. When you’ve done this, edit some more. Make sure to use the show object, show object history, download relation, and other tools that download data. Watch what API calls are made, compare them against the API documentation, and understand what it’s doing.

6. Explore getting object information

There’s a few ways to get object information. The obvious one is the “browse” pages at https://www.openstreetmap.org/way/<N>, but also include history view in JOSM and OSM Deep History. The first page doesn’t use the API and the second two do. The goal of this project is to make the first page use the API.

7. Examine a browse page

The next two steps are a form of homework and necessary to write your proposal. Look at a the node browse page for node 5324545411. Write down what API calls are needed to get all the information on it. It should be possible to do it in a fixed number of API calls, in this case four calls.

8. Identify missing API calls

For some browse pages it’s not possible to get all the information in a fixed number of API calls. Take a look at way 471813907 and see what infomation is missing or would require recursive API calls. Part of the project will be proposing and implementing new API calls to fill the missing needs.

Some more background is found in some emails from a year ago