Talk:API

Rename 'REST' page as 'API' ...or 'Protocol' (DONE)

Currently 'API' redirects here, which is good, but it would be even better if we moved this content to the 'API' page, since this page is describing the API. One characteristic of the API is that it follows the 'REST' approach (as described on the page), but basically it's a page about the API right?

I know this has existed as the REST page for a long time now, but a redirect from REST->API should avoid any confusion for people who are used to going to the 'REST' page. Any other reason why we should not make this move? -- Harry Wood 11:54, 12 April 2007 (BST)

Oh. Things have been rearranged. It's now referred to as "OSM Protocol" in various places. Is it a "protocol" or an "API"? Maybe that's another discussion. This page is still called 'REST' -- Harry Wood 17:56, 18 April 2007 (BST)

I spend some time with cleanup and preparations for version 0.4. Without asking I changed the name from API to protocol. According to my understanding an Application Programming Interface (API) is always related to programming (e.g. the OSM Ruby API, the OSM Java API). Here however, we are actually defining here the way the information is exchanged between 2 computers by defining the semantic, data structure and behavior of content exchanged within HTTP-messages. The specification is programming language independent. This is what usually is referred as 'protocol'. The above was my motivation for replacing the term API by protocol. Any thoughts? --Josy 17:35, 19 April 2007 (BST)

Well I tend to associate 'protocol' will more low-level networking. Protocols can always be layered on top of each other. This thing is already operating on protocols 'HTTP' and at a lower level 'TCP/IP' of course. But this OSM usage is at the 'application level'. OSM is supporting various application specific operations. The word protocol seems too low-level.

But then as you say "API" isn't quite right either. People are always talking about "the OSM API" on the mailing list, but ideally I suppose we'd switch to referring to it as something more technically accurate. It's an "OSM web service"... but not to be confused with WMS. hmmmm

Anyway probably doesn't really matter. As long as people can find the info. Well done for cleaning-up to clarify the versions. -- Harry Wood 12:56, 23 April 2007 (BST)

Yes it is an Application Protocol. It realizes OSMs use cases on remote database access. It is very application specific. I guess the awareness of low level protocols is higher than that of high level protocols. The deeper down the protocol stack, the higher the chance protocols have been standardized. E.g. Bluetooth has standardized also all application protocols. Sometimes they call the upper most protocol layer 'Profile'.

The term "web service" comes close, however it is very ambiguous and as buzz word used by many people for different things. Unlike the term "protocol", the term "web service" does not refer to a specific layer, however to all layers together (including HTTP, TCP/IP, service discovery, etc.). --Josy 09:54, 29 April 2007 (BST)

OK yeah I see what you mean with the bluetooth example. So with this in mind, this 'REST' page should be renamed 'Protocol'. That would fit nicely with the new pages you've created. -- Harry Wood 16:21, 1 May 2007 (BST)

OK. I am currently considering to move the HTTP description part of the OSM Protocol Specification into a separate HTTP spec. document. This should describe the HTTP Protocol (GET, PUT, DELETE, etc.) as used by OSM also refer to the W3C HTTP pages. This HTTP description applies to OSM Protocol Spec. Version 0.3, 0.4 and will likely also apply to 0.5, 0.6, .. if those use HTTP. So there is no need to duplicate the HTTP description for every version of the OSM Protocol?

I also plan to do some nice drawings for the protocol stack including the client and server. This should become the new entry page. Maybe it would be named 'OSM protocol stack' However it will take some time, as I have limited internet access at the moment. Thus I'd rather wait with the page rename until that is accomplished. --Josy 22:12, 3 May 2007 (BST)

I created the HTTP-Specification page and moved all HTTP-related items to that page. Also I created drawing depicting the protocol stack architecture.--Josy 19:57, 6 May 2007 (BST)

Looks good Josy.

I modified my Component overview diagram to show this as Protocol. Actually I called it the "Protocol Interface" (needed something to put in a component box)

So I'm going ahead now with renaming REST -> Protocol -- Harry Wood 10:28, 29 June 2007 (BST)

Hi Harry

Thanks. Even, if some pieces are still undocumented, I finally came somewhere near where I wanted to get with the page. Lately I renamed 'Protocol' to 'The OSM Protocol Stack'. Protocol Interface is not a bad term either. Should we rename again? Nothing in OSM had so many names. (-: Josy

Rename 'Protocol' to 'API'

This is crazy. No-one outside the wiki calls it anything other than an API. Let's change it back. --Richard 12:02, 20 February 2009 (UTC)

Well the page was never called "API" actually. I suggested renaming it to that (used to be called "REST" for a long time). Josy preferred "Protocol". I think he was hoping people would start to adopt that, but no... everyone still calls it the API. -- Harry Wood 22:47, 22 February 2009 (UTC)

Hm - the purpose of the wiki should be to document what people already do, not to tell them how to refer to things (but therein lies the whole tagging argument). Anyway - can you fix it, Harry (as an important sysop an' all that)? When I try and rename it, it tells me that there's already a page called API. --Richard 10:00, 23 February 2009 (UTC)

DONE. Now called 'API'. There's some pages linking to the old title: Special:WhatLinksHere/OSM Protocol Stack ...actually surprisingly few. -- Harry Wood 12:18, 23 February 2009 (UTC)

Is anyone opposed to renaming the specification pages? (OSM_Protocol_Version_0.6 -> OSM_API_Version_0.6). I also think that the "OSM Protocol Stack Overview" image and "HTTP Protocol Specification" can be deleted as they serve no real purpose. We should only describe the OSM API and not every single underlying protocol or else we'd end up documenting everything from HTTP to TCP/IP. --LarsF 14:00, 13 September 2009 (UTC)

Yep. Dont really need the 'OSM' either. How about "API v0.6"? -- Harry Wood 22:30, 13 September 2009 (UTC)

Good idea! If we change it now let's do it right. --LarsF 03:45, 14 September 2009 (UTC)

There's a lot of links will need swapping if you do this though: Special:WhatLinksHere/OSM_Protocol Version 0.6 -- Harry Wood 08:52, 14 September 2009 (UTC)

I have begun this with the old API versions (0.3 through 0.5) and I will do 0.6 later. The old page name redirects to the new name so this is not a big problem but I still have updated most of the links on the pages to the new name (excluding User- and Talkpages). And I've used your naming schema everywhere (API v0.3, API v.0.4, and so on), I think it looks a lot better now. The Protocol stuff was just confusing. I'm done now. I believe I have fixed most links and everything seems to be working --LarsF 15:59, 14 September 2009 (UTC)

Wishlist for API

Is there any wishlist or suggestion page for features to the next version of the API? --Skippern 13:13, 15 November 2009 (UTC)

As far as I know there is no such page on the Wiki. There was an API 0.7 page for a short time (if I remember correctly) but it has been removed to prevent confusion. You could try posting your suggestions or questions on the dev mailing list. That would make fairly certain that the "right" people read your suggestions --LarsF 16:50, 15 November 2009 (UTC)

We do have an API v0.7 page. It's in "brainstorming" mode, and has been for years. At one stage this was a bit of joke, and some quite silly ideas were listed on there. It seems to have been tidied up a bit. Certainly the top sections of that page make sense. On the whole though wiki-brainstorming is not the way to get such things done. Core OSM developers tend to follow more of a "Rough consensus and running code" approach. For small tweaks, we also use bug tracking: Rails port/Development#Bugs -- Harry Wood (talk) 13:51, 23 May 2013 (UTC)

Mention XAPI

Hey guys,

I started taking an interest in OSM and the underlying GIS for a pet project of mine. However, I needed some complex API (that XAPI provides) and I find it was a bit too hard to find to my taste. Do you think it would be worth some mention on your base API page?

thanks

Page move

Maybe move it under Editing API? To make it less confusing for newbies looking for API to download data in bulk? Maybe even with disambig at API page? Mateusz Konieczny (talk) 05:38, 26 December 2022 (UTC)