LyricWiki API/REST
Comments12this wiki
< LyricWiki API
Contents |
LyricWiki:REST
Edit
The REST API is an alternative method of accessing the same backend as the SOAP. The primary difference being that the SOAP uses a standardized XML format and the REST allows you to make simple requests through the command-line.
NOTE: The results of the REST API are cached for up to 2 hours. This makes our system run a lot faster, but is something you should be aware of during testing. If you need to see the up-to-the-second info, since the caching is based on the URL, just add additional parameters (like "&1123124" or another random number after the ampersand).
How to use the REST APIEdit
Making a requestEdit
Requests are made by passing parameters in through the URL for the function and optionally supplying a format for the response.
A request should contain:
- func - The function name to call (eg: getSong). NOTE: WHILE THE REST IS BEING DEVELOPED, TEMPORARILY ONLY A FEW FUNCTIONS ARE AVAILABLE. IF YOU NEED OTHER FUNCTIONS SOON... RATTLE MY CAGE. If you would like to simulate the results of a getArtist() request, just pass in an artist and no song.
- getSong() - default if no 'func' is provided.
- getArtist() - defaults to this if no song is provided and func is either blank or 'song' (ie: it's just a fallback for getSong() with no song).
- getHometown()
- ... - All other options should be specified by key-value pairs. So since getSong() takes 'artist' and 'song' parameters, you need to pass in 'artist' and 'song' through the url.
- fmt - Optional format of the response. See Response Formats below.
- Optional 'X-Wikia-API-Key' header. Include your key if you want lyrics posted via the API to be attributed to your account. See the API Gate panel for more info.
Example requestsEdit
- Get the lyrics to Tool's Schism in XML format:
- Get the lyrics to Breaking Benjamin's "Until The End" as a block of text:
- http://lyrics.wikia.com/api.php?func=getSong&artist=Breaking_Benjamin&song=Until_The_End&fmt=text
- (And why is it a "block of text"? Because for all fmt=text requests, the author is returning the wrong HTTP Content-Type: text/html, instead of the correct text/plain!!)
- Get the entire discography (list of songs only, not lyrics too!) for Linkin Park, displayed as HTML:
- If you want to get an XML version of the discography, it is recommended that you add the 'fixXML' parameter to get valid XML. The default is still invalid-XML unfortunately (this was needed so that we didn't break existing apps that used the invalid format).
Response FormatsEdit
The format of the response is specified by the 'fmt' parameter. This case-insensitive value defaults to 'html'.
- HTML (default) - Lightly formatted lyrics result. Example HTML lyrics.
- TEXT - Raw lyrics. Other fields are not returned. Example of just text lyrics.
- XML - Light-weight XML version of the same values that the SOAP would return. Example of lyrics in xml.
- JS/JSON - JS and JSON format currently only support getSong method. See samples below for usage. Example of lyrics in JSON Example of pure JS version
Samples that use RESTEdit
- Flash Song Search, A Free and Easy-to-use Flash to get lyrics:
- It's web based, so you can use it without installing anything except web browser and flash.
- The project's link: http://lyricapi.googlepages.com/main-en.html
- JavaScript/JSON API example:
- See my blog post for instructions on how to use JavaScript with JSON format to statically or dynamically load lyrics: techblog.molindo.at
- JavaScript API example:
- Give Me Lyrics is a lyric searcher of Lyricwiki. It extends Fuzy's code above and make search available.
- iPhone WebApp LyrSearch
- LyrSearch is a lyric searcher for the iPhone.
Documentation on each function/methodEdit
For details about the input and output of each function/method please refer to the SOAP's request/response documentation.