LyricWiki:SOAP

From LyricWiki

NOTE: This is a very preliminary version (and will undoubtedly change as it is being implemented on the server-side). The documentation is here so that you can provide feedback.

[edit] Intro

We are considering making some drastic changes to the API relatively soon. In order to be able to notify API developers of changes, we're starting a mailing list. It will only send announcements (discussion will still take place on LyricWiki) so the emails should be very infrequent.

Subscribe to LyricWiki API Developers

Email:

Visit this group

The LyricWiki SOAP web service API uses a server written with nuSOAP for PHP, but follows the WSDL standard so that any system that uses WSDL files can easily access the web service. Some languages/environments that are known to easily integrate using WSDL files are PHP (using the nusoap package), Java, and .NET (C#). The functionality is not done for the server yet, but it exists and will return default values that may help in testing during your development of extensions (the server should be done in a matter of days).

Once the server is finished, a PHP file will be made available that wraps the web service into a few simple functions so that you can use the web service by simple calling functions as if they were on your local machine. The early predecessor of this file is the SOAP client test-script (it is a good example of PHP code which uses the SOAP API).

The WSDL file can be found here.

Basic documentation for the web-service (not the PHP file that will wrap it) can be found here.

UPDATE April 2, 2007: We added a return value for the url to getSong() and getSongResult(), since the page name may differ from what would be expected by the request (due to redirects, etc.), this should be used instead of URLs you generate yourself since it reflects our naming conventions and the current state of the database.

[edit] A note on the standard MediaWiki API

At the time when api.php, the LyricWiki API, was created, the standard MediaWiki API did not yet exist. When the MediaWiki API was added, it unfortunately used the same filename. Because of this, the MediaWiki API was renamed to mw_api.php.

[edit] Portability Testing

Tested on

• PHP (PHP5 SOAP Library) - Works PHP5's built in SOAP Library works.
• PHP (nuSOAP) - Works (see external links)
• PHP (WSF/PHP) - Works Small PHP library written using WSF/PHP [1]
• .NET framework 2.0 and 3.0 - Works (Except for a few Functions)
• Perl- Works Perl module for fetching lyrics by Dave P available on CPAN
• Flash - Partially tested : The crossdomain.xml file has been added to the root directory so that the security warning is not displayed to users. Since 'return' is a reserved word in flash, getSongResult() should be used instead of getSong().
• Python - Partially tested : Using ZSI.
• SOAPpy - Bugs : has a problem with the content-type header. Spews an error (but recieves the lyrics if you put debug output on this can be seen).
• Ruby - Bugs : Any character outside of ASCII is returned malformatted. See talk page.
• Java & Axis - Unknown : The WSDL file does not work as provided, but a fix (setting namespace for array types in two places) can be performed to make it work. See talk page.
• Javascript - Uses the alternative REST version. Please note that this is the exact same backend code with a different frontend.
• C#.NET (VS & Mono) - Testing by adding a web reference and running CheckSongExists() & getSong(). Both work great!
• AppleScript: works fine with the "call soap" api, for getSong(). Some problems may occur with accentuation (french, spanish...)

[edit] Current Progress

Currently the WSDL file works and the following methods are working: (note: SOTD is short for Song of the Day)

• checkSongExists()
• getSong()
• getSongResult() - an alias for getSong() which returns the value as 'songResult' instead of 'return' since 'return' is a reserved word in flash.
• getSOTD()
• getArtist() - also works with api.php (use func=getArtist at the end of the url to use this function. ex: [2]).
• getHometown()
• postAlbum()
• postSong()

[edit] Authentication

Since anonymous users are allowed to edit LyricWiki, they are also allowed to use the SOAP webservice to make changes. However, if you would like to associate any SOAP webservice changes that you make with your user-account, this can easily be achieved by setting the SOAP headers 'username' and 'password'. If you are using nuSOAP (PHP), here is an example of how to do this:

$LW_USERNAME = "your_username_here";
$LW_PASSWORD = "your_password_here";
require_once('nusoap.php');
$client = new soapclient('http://lyricwiki.org/server.php?wsdl', true);
$err = $client->getError();
if ($err) {
	echo '<h2>Constructor error</h2><p>' . $err . '</p>';
} else {
	$proxy = $client->getProxy();
	if(($LW_USERNAME != "") && ($LW_PASSWORD != "")){
		$headers = "<username>$LW_USERNAME</username><password>$LW_PASSWORD</password>\n";
		$proxy->setHeaders($headers);
	}
}

[edit] Allowed Requests/Responses

I will be adding amazon links (throw them out if you don't want them) and some other Request/Response pairs. Stay tuned.

There are two types of ways to push updates to LyricWiki. Make[x] and Update[x]. When using Make[x], if the item already exists, the update is not applied, and an error is returned. This is considered safer and should be used any time you are adding completely new items, even if you have already used the API to check if the item exists. When using Update[x], the item is created/changed regardless of whether it existed previously. If the page did not exist previously, a warning is returned in the 'Message' tags.

[edit] Future Tasks

• Allow the webservice to post/retrieve album art given the Song or the Album (don't require the album, figure that out automatically). Refer to this article.
• Normalise CaPiTaLiSaTiOn - again, people are naming pages inconsistently and this should be handled in the search (either by searching all lower case or UPPER CASE). i.e. a case-insensitive search (again to be implemented server side to speed this up).
• Allow lookups of pages other than songs/artists etc. For example, it would be useful to be able to view the pages listing songs in a particular language or in need of language identification. However, since these pages are automatically indexed, modifying them directly is not desirable. This can be done using the default MediaWiki APIs, but those need to be fixed to work on the same domain as our API.
• Make the REST code actually RESTful (with meaningful error messages).
• Make the XML more well-structured.
• Have the name of the client-program passed in so that we can work with developers to figure out problems when things are going strangely.

[edit] Related Links

• REST (REpresentational State Transfer) - alternate method of accessing the API using these same functions but making requests via HTTP "GET" requests.
• Failed SOAP requests - This lists contains the 50 most commonly failed requests. It helps find highly-desired missing songs/artists/redirects and shows us ways that we could improve the searching ability of the SOAP.
• Plugins - List of plugins (and other sites/apps) that implement the SOAP. Please add your own application once it is complete.

[edit] External Links

SOAP on Wikipedia.
nuSOAP tutorial whose code was used to build the server and test-client.
Generic SOAP Client for testing.
WSDL Essentials chapter from Web Services Essentials.
Tutorial - Creating and Consuming Web Services with PHP
Tutorial that uses complex types in writing the web service (more for server work than client-side).
Tutorial write your first lyrics lookup using C#.NET.
Tutorial (also server-side).
API to other lyrics sources