define XML namespace for output of web API
Closed, ResolvedPublic

Description

It would be useful to define an XML namespace for any XML-Formatted output of the web API. This would allow us to embed elements from that output in other XML documents easily. My own use case is embedding <rc> tags in XMPP stanzas.

I would suggest to use the URI http://www.mediawiki.org/xml/api-0.1 for the namespace. In practice, this would mean that the top level <api> tag returned by the API would become:

<api xmlns="http://www.mediawiki.org/xml/api-0.1">

This should have no impact whatsoever on backward compatibility, except perhaps for clients processing the XML using naive regular expressions. I believe it would be ok to break those, since they rely on things that are never guaranteed in XML.


Version: 1.17.x
Severity: enhancement

bzimport added projects: MediaWiki-API, Easy.Via ConduitNov 21 2014, 11:08 PM
bzimport set Reference to bz24781.
daniel created this task.Via LegacyAug 13 2010, 2:33 PM
Reedy added a comment.Via ConduitAug 13 2010, 3:35 PM

I agree on the breakage - It's not as if we're breaking conformity to valid xml etc.

IIRC (NB, I've not done much with this), we don't need to have anything served at that URL do we, it's just like an identifier?

Catrope added a comment.Via ConduitAug 13 2010, 3:37 PM

Would anything need to be present at that URL? It currently 404s. If it needs like a full schema of possible outputs, that's a problem.

daniel added a comment.Via ConduitAug 13 2010, 3:43 PM

no, namespaces are pure URIs. nothing needs to be there. Namespaces also don't require any schema or dtd.

it's useful to have some kind of documentation at that location though.

Reedy added a comment.Via ConduitAug 13 2010, 5:49 PM

http://www.mediawiki.org/wiki/api would be the easiest to have documentation there ;)

Bawolff added a comment.Via ConduitAug 13 2010, 8:35 PM

This should have no impact whatsoever on backward compatibility

If you're using a namespace aware xml parser to parse the api, this could break it if your code expects the api output to have no namespace, and now it suddenly does.

daniel added a comment.Via ConduitAug 13 2010, 8:48 PM

at #5: how would the code expect that? In what way would one usually rely on the fact that no namespace is used? And if so, why use a namespace aware parser?

I understand the point in theory, but can't imagine when it would actually happen.

Bawolff added a comment.Via ConduitAug 13 2010, 8:50 PM

It is still rather far fetched, I just thought I should mention it because it seemed more likely breakage case than the regex one.

Reedy added a comment.Via ConduitJan 3 2011, 11:34 PM

Bringing some life back here.

The fix is fairly simple, and there are possibly some breakages. I'm almost inclined to just say "tough" to those not doing it properly

Thoughts?

Ilmari_Karonen added a comment.Via ConduitJan 3 2011, 11:46 PM

Although I would defer to those more familiar with all things XMLish, I'm inclined to agree with Reedy here. Anything that breaks because of a change like this was really already broken. (Of course, having said that, I bet my own API clients are going to choke on it... :)

Catrope added a comment.Via ConduitMay 13 2011, 2:33 PM

Daniel poked me about this at the hackathon, gonna start doing this in a minute.

Catrope added a comment.Via ConduitMay 13 2011, 4:35 PM

Fixed in r88007. I used http://www.mediawiki.org/xml/api/ as a namespace and created that URL on the cluster as well.

ArielGlenn added a comment.Via ConduitOct 6 2011, 12:06 PM

Not completely breakage-proof, it seems: see the comment about XPATH at http://www.mediawiki.org/wiki/Special:Code/MediaWiki/88007#c23862 reported by a user of the jdom library.

Svick added a comment.Via ConduitOct 6 2011, 12:17 PM

Just a note, this really is a breaking change for some parsers. Specifically, for the one I'm using: LINQ to XML in .Net. It is namespace-aware and when a namespace is present, it has to be always used.

For example to get the root node, previously you would do:

var elem = document.Element("api");

With the namespace, the previous code wouldn't work and would have to be changed to:

XNamespace ns = "http://www.mediawiki.org/xml/api/";
var elem = document.Element(ns + "api");

I'm not arguing against the change (I think it's a good idea), but I wanted to let you know that it's going to be a breaking change, at least for some people.

bzimport added a comment.Via ConduitOct 6 2011, 7:48 PM

Bryan.TongMinh wrote:

Since this apparently is a breaking change, can we revert it and make the addition of a namespace optional, perhaps with the boolean includexmlnamespace?

Catrope added a comment.Via ConduitOct 6 2011, 7:55 PM

(In reply to comment #14)

Since this apparently is a breaking change, can we revert it and make the
addition of a namespace optional, perhaps with the boolean includexmlnamespace?

Sounds good. Mind doing this yourself? I'm busy packing now and will be traveling for the next few days.

bzimport added a comment.Via ConduitOct 6 2011, 8:16 PM

Bryan.TongMinh wrote:

r99135

Catrope added a comment.Via ConduitOct 6 2011, 8:44 PM

(In reply to comment #16)

r99135

Deployed.

RobLa-WMF added a comment.Via ConduitOct 6 2011, 10:18 PM

This would make me sad if this is a permanent option, since this is option bloat. LINQ to XML in .Net is presenting a really broken API if it's requiring the caller provide the namespace URI to parse the resulting XML. Not the end of the world if we have to leave it in there, but wow that's sad.

Catrope added a comment.Via ConduitOct 6 2011, 10:19 PM

(In reply to comment #18)

This would make me sad if this is a permanent option, since this is option
bloat. LINQ to XML in .Net is presenting a really broken API if it's requiring
the caller provide the namespace URI to parse the resulting XML. Not the end
of the world if we have to leave it in there, but wow that's sad.

If you think this is sad, you ain't seen nothin' yet ;)

bzimport added a comment.Via ConduitOct 7 2011, 6:44 AM

shubinator1 wrote:

For the record:
Many XML parsers, including (as noted) JDOM and MSXML (on top of which the .NET XML library, among many other libraries, is built) are namespace-aware. This isn't "not doing it properly", it's arguably doing it properly, since two XML nodes that only differ in which namespace they belong to should be treated as different node types.

Add Comment

Column Prototype
This is a very early prototype of a persistent column. It is not expected to work yet, and leaving it open will activate other new features which will break things. Press "\" (backslash) on your keyboard to close it now.