Last modified: 2010-10-28 23:37:24 UTC

Wikimedia Bugzilla is closed!

Wikimedia migrated from Bugzilla to Phabricator. Bug reports are handled in Wikimedia Phabricator.
This static website is read-only and for historical purposes. It is not possible to log in and except for displaying bug reports and their history, links might be broken. See T27648, the corresponding Phabricator task for complete and up-to-date bug report information.
Bug 25648 - API discovery information: add RSD link in page <head>
API discovery information: add RSD link in page <head>
Status: RESOLVED FIXED
Product: MediaWiki
Classification: Unclassified
API (Other open bugs)
unspecified
All All
: Normal enhancement (vote)
: ---
Assigned To: Brion Vibber
http://en.wikipedia.org/wiki/Foo
: patch, patch-need-review
Depends on:
Blocks:
  Show dependency treegraph
 
Reported: 2010-10-25 20:40 UTC by Brion Vibber
Modified: 2010-10-28 23:37 UTC (History)
7 users (show)

See Also:
Web browser: ---
Mobile Platform: ---
Assignee Huggle Beta Tester: ---


Attachments
ApiRsd (3.74 KB, patch)
2010-10-26 20:33 UTC, Bryan Tong Minh
Details
Tweaked ApiRSD patch (6.61 KB, patch)
2010-10-26 22:19 UTC, Brion Vibber
Details

Description Brion Vibber 2010-10-25 20:40:38 UTC
One of the things I've noticed after spending some more time working with non-MediaWiki systems is that we don't always have machine-accessible information within our web pages. A fair amount of data is available in the global JS vars, but that's not trivial to read from an application that's not running in the browser.

Given the URL to some MediaWiki page -- say http://en.wikipedia.org/wiki/Foo -- we really should be able to do at least two key things:

1) Get the API root URL
2) Get the wiki page title for the current page (should be treated under a separate bug if details needed)


*If* we can reliably pull the JS vars, we could reconstruct the API root as wgServer + wgScriptPath + 'api' + wgScriptExtension, but honestly I wouldn't want to have to rely on that, as the data structuring isn't very standardized.

I'd recommend using the RSD "Real Simple Discovery" system, which both WordPress and StatusNet are using to expose their WordPress and Twitter API URLs:

http://cyber.law.harvard.edu/blogs/gems/tech/rsd.html

Here's an example on StatusNet... pages contain a discovery link:

  <link rel="EditURI" type="application/rsd+xml" href="http://identi.ca/rsd.xml"/>

Which points to a document like this:

<?xml version="1.0" encoding="UTF-8"?>
<rsd version="1.0" xmlns="http://archipelago.phrasewise.com/rsd">
 <service>
  <engineName>StatusNet</engineName>
  <engineLink>http://status.net/</engineLink>
  <apis>
   <api name="Twitter" preferred="true" apiLink="https://identi.ca/api/" blogID="">
    <settings>
     <docs>http://status.net/wiki/TwitterCompatibleAPI</docs>
     <setting name="OAuth">true</setting>
   </settings>
  </api>
  </apis>
 </service>
</rsd>

So for MediaWiki we could output something like this:

<?xml version="1.0" encoding="UTF-8"?>
<rsd version="1.0" xmlns="http://archipelago.phrasewise.com/rsd">
 <service>
  <engineName>MediaWiki</engineName>
  <engineLink>http://mediawiki.org/</engineLink>
  <apis>
   <api name="MediaWiki" preferred="true" apiLink="http://en.wikipedia.org/w/api.php" blogID="">
    <settings>
     <docs>http://mediawiki.org/wiki/API</docs>
     <!-- We could in theory expose some info like authentication -->
     <!-- support here, or leave it for meta=siteinfo -->
     <setting name="OAuth">false</setting>
    </settings>
   </api>
  </apis>
 </service>
</rsd>

This should be pluggable, so extensions that add their own machine APIs can register themselves in there. (For instance a blogging extension could provide a WordPress-compatible API.)
Comment 1 Bryan Tong Minh 2010-10-26 07:23:18 UTC
Since rsd.xml needs to be different for each domain, I think it can be best generated by api.php?action=rsd. Is there any problem if the entry point is not called rsd.xml?
Comment 2 Sam Reed (reedy) 2010-10-26 12:44:37 UTC
Looks cool.

On a similar note, it'd be nice to get the XML Schema (bug 14025)

One would presume/hope, that as long as the type and rel is the same, it could point whereever...
<link rel="EditURI" type="application/rsd+xml"
href="http://identi.ca/rsd.xml"/>
Comment 3 Brion Vibber 2010-10-26 19:59:42 UTC
Yeah, the URL shouldn't matter here. API probably is a good place to put it, plus I like the irony of exposing the discovery for the API in the API. ;)
Comment 4 Sam Reed (reedy) 2010-10-26 20:01:32 UTC
(In reply to comment #3)
> Yeah, the URL shouldn't matter here. API probably is a good place to put it,
> plus I like the irony of exposing the discovery for the API in the API. ;)

Yay, recursion! :D
Comment 5 Bryan Tong Minh 2010-10-26 20:33:37 UTC
Created attachment 7758 [details]
ApiRsd

ApiRsd patch.

Didn't feel like digging through our skin system how to add the <link> element, so that still needs to be done. Feel free to commit, I may or may not have time to work further on this.
Comment 6 Brion Vibber 2010-10-26 20:55:34 UTC
Awesome, I'll take a peek over it.
Comment 7 Brion Vibber 2010-10-26 22:19:07 UTC
Created attachment 7759 [details]
Tweaked ApiRSD patch

I've done a little testing and enhanced the patch a bit:

* added the <link> to page header
* tweaked the XML output to fix some attribute vs child-element oddities
* tweaked the hook point so we can hand a slightly simpler array to extensions to use.

This looks about right to me (though I wanna double-check in a bit), and I can add some sample extension API info like so:

$wgHooks['ApiRsdServiceApis'][] = 'barfo';
function barfo(&$apis) {
	$apis['Atom'] = array(
		'apiLink' => wfAppendQuery(wfScript('api'), array('action' => 'atompub')),
	);
	$apis['Twitter'] = array(
		'apiLink' => wfAppendQuery(wfScript('api'), array('action' => 'twitapi')),
		'docs' => 'http://apiwiki.twitter.com/Twitter-API-Documentation',
		'settings' => array(
			'OAuth' => false,
		)
	);
	return true;
}

Things to double-check:
* confirm all is well with it served as generic application/xml (should be fine)
* double-check if we're required to make URLs fully-qualified (in which case it wouldn't hurt to enforce it on extension-provided URLs)
* test: throw in WordPress and Twitter API points as in the ext example above, and make sure that WordPress and StatusNet Android/iPhone clients actually pick them up when given the wiki's base URL.

May need to add hook doc entry.
Comment 8 Bryan Tong Minh 2010-10-28 19:20:59 UTC
r75621
Comment 9 Brion Vibber 2010-10-28 21:38:03 UTC
So far so good :D

I can confirm that StatusNet Mobile can do discovery from our RSD if I manually add Twitter API info. YAY

WordPress for iPhone 1.x fetches the RSD data but decides it's unsupported (haven't totally worked that out) while WordPress for iPhone 2.x apparently doesn't actually do RSD and looks for some hardcoded URL subpaths. :(
Comment 10 Gurch 2010-10-28 23:37:24 UTC
> 1) Get the API root URL

Glad to see I wasn't the only one having trouble with this. Wasn't so hard to parse out the JS variables myself... until ResourceLoader showed up and suddenly those were buried in a separate file, served from somewhere else.

This adds a third thing to look for, but eventually one day will make things easier. :)

Note You need to log in before you can comment on or make changes to this bug.


Navigation
Links