Send to a friend
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.
Contents |
Intro
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.
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.
Portability Testing
Tested on
- PHP (nuSOAP) - Works (see external links)
- .NET framework 2.0 and 3.0 - Works
- 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 : Someone mentioned they had issues... I don't think we ever fixed that. 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...)
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: [1]).
- postAlbum()
- postSong()
- searchArtists() - but it's not too great (queries to get other close matches took 15 seconds minimum).
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);
}
}
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] Searching
|
[edit] Fetching
|
[edit] Updating Pages
|
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 contractions like "Don't" and "Can't" to either USE or NOT USE the apostrophe - the pages are inconsistent and this makes lookups that much slower (you have to do one with apostrophes and one without - if this was handled server side it would be that much faster.)
- 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).
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.
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 (also server-side).
API to other lyrics sources
+ 
