From OpenStreetMap Wiki
Jump to: navigation, search

New API Proposal (by spaetz)

I think the t@h server has become quite a tangled legacy mess over time. And you can feel that our client API has been kludged on over time too (e.g. blankness information based on .png file size is ingenious yet hacky).

I think we should sit together and discuss on how this could be improved. 1)Let's design a clean Server/Client API 2) and let's clean up the server. 3) (I can't speak for the client :-))

re 2)Concerning the Server, I am experimenting with Django/Python (I am absolutely no ruby/rails fan). No special reason, I just enjoy playing with it. My experiment is online: This is a low-priority experiment though, so don't expect it to be working tomorrow. Login with regular OSM-Login works already, no more hunting of admins for signing up for t@h. During first login, the server checks the OSM login and caches that locally so the load on the main API server should be negligible. I intend this server to contain the request administration, and the upload function (the unzipping should probably be handled by a background daemon as now, and not by an apache instance but that is open for discussion and your expertise)

re 1) The other thing is the Client API. If deelkar could say what would make his life easier, then we could work around that. At the same time I would like to improve our possibilities (ie go away from a strict z12-upwards tileset).

-A request could specify a min-zoom and a max-zoom, which would allow to split complex tilesets in z13 tilesets instead. A click on informationfreeway would request z12-z17. If it's a complex tile the server might want to hand that out as 4 z13-z17 requests and a z12-z12 request or something similar.

These are the client transactions that I can see:

a) ask for a new render order (client gives maximum complexity, possibly receive z12 blanktile status from server)

b) give status feedback (ping-still working, error with reason, upload successful)

c) upload resulting tiles

c1) give feedback on tile complexity for z12 tiles (eg. downloaded OSM file size?)

d) notify server about blank tiles

optionally: e) request information about newest client version, request latest stylesheets, etc...

f) server might want to push other messages to the client during communications that can be displayed to the user (announcing server downtime or whatever)

Should there be more? What information should be transmitted? and in what form?

- Do we want a REST-like interface like the OSM API? (/request/get) (/request/1234/ping). - Should we transfer blank tile information through the API rather than working with the png file size? (/api/blank/1(layer)/2(x)/3(y)/12(z)/sea) (/api/blank containing a list of blank files) (or do we want to put a list of blank tiles in a special file in the upload zip?)

- And the API data itself (auth information, feedback messages), do we do HTTP POST forms as now? some XML sheet that describes what tiles are blank sea/land? Whatever is easiest for the client... i have no experience in designing Web APIs so I am grateful for input.

What I am trying to do here, is take a step back from what we have and to think about what we need. I know that we have a complete client/server, so rewriting the server is evil, but if I have fun doing just that, then why not?


Clientside-view (by Deelkar)

I am currently having fun exploring different methods of requesting and mangling of data in the client, but the client, too, needs some cleaning up.

Secondly the client should handle it's own updating, instead of relying on the person running it to periodically check svn, maybe push version info to the client, rather than let the people poll.

Requests that do change stuff on the server, and be it just a "keepalive" should be POST, uniformly.

It would be nice if we could split tilesets up over multiple archives, which then get reassembled on the server before processing, each, say, 8 MB in size because we do have trouble with some transparent proxies at ISPs not allowing such large POST requests, maybe alternate upload methods.

You might want to supply "preferred layer" by the server, so when a render-request gets triggered by a 404 on captionless, the server asks for captionless first, the rest of the tilesets would be nice-to-have, but not mandatory (this would help for the captionless tiles that are on complex city areas, so you would have at least some feedback, as it is now the client will stop rendering mid-"tile"-layer and not even start maplint and captionless). However you would need to re-think what can or cannot fulfill a render-request, currently any layer z12 tile satisfies the request, regardless what triggered it.

c) Maybe we should think about uploading multiple tilesets/layers in one archive?

c1) Maybe use resulting svg file size(s) as complexity indicator? Or, if even possible, inkscape process size? (I currently have no idea how to monitor this from a perl script)

d) Notifying server about blank tiles, that's something I've thought about quite often, I was thinking about some sort of "index" file in the zip that would contain meta-info about the returned tileset.

e) I like the idea that the server can notify the client of new versions or new stylesheets / other info.

f) I have in mind something like the server message which is some "cool"/"strange" comment which changes to an announcement if needed.

For client-server communication I'm basically open towards anything that LWP::Simple and LWP::UserAgent support... (I think POST would be the easiest, but I'm not strictly against anything else, other than maybe having to implement it ;))