Talk:API v0.4

Any chance the way the API is described could be made easier to understand? I've written code that calls the API (0.3 and 0.4), I've contributed the odd patch to the API (0.3 and 0.4), and I'm struggling to figure out what most of the documentation means... Gagravarr 14:18, 18 April 2007 (BST)

Hello Gagravarr. Thanks for the feedback. I think it has improved a little by node. I agree with your opinion. It is the first http-based protocol I describe. I am struggling to simplifying the description (partly because http violates layering), while keeping the description complete. Also I have here only the ruby code, not the http messages. --Josy 21:56, 18 April 2007 (BST)

Maybe it's worth having two parts to each API call's documentation - one the full, rigorous API documentation, and the other a "I know about RESTful APIs, just tell me what URL to call, and what parameters it takes" succinct mini doc. That way, people new to the API get the full description they want, but experienced people can quickly see what the parameter is for the call they want to make. Thoughts? Gagravarr 10:14, 19 April 2007 (BST)

This sounds like the right track to me. The rigorous protocol specification is important for experienced people to get the implementations right. The rigorous part might even include XML-DTDs or schema as description for XML data transfered as payload.

The HOWTO part is considered for newbes with http background and explains the protocol by showing protocol traces for certain actions. E.g. Retrieve a node. Upload a segment. This part would be rather 'informative'.

To keep those documentations consistent it would be helpful to have those in the same document. Maybe using different background colors.

Furthermore it may be useful to have an abstract representation of the commands. Those are better undertandable.

Example of abstract command representations:

http:/www.openstreetmap.org/get/node?ID=34 <=> get_node(34)

http:/www.openstreetmap.org/way/4532/history <=> get_way_history(4532)

http:/www.openstreetmap.org/map?bllon=400,bllat=300,trlon=5000,trlat=7000 <=> get_map(400,300,5000,7000)

	Method	get_request_command
HTTP-Command	GET	/map?bllon=x1,bllat=y1,trlon=x2,trlat=y2
Abstract representation	-	get_map-req (x1, y1, x2, y2)

Any feedback?

--Josy 17:20, 19 April 2007 (BST)

I just found this page describing the XML Schema used by the REST API. This all should be in one place--Josy 18:57, 19 April 2007 (BST)