LyricWiki:REST
From LyricWiki
Contents |
[edit] LyricWiki:REST
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).
[edit] How to use the REST API
[edit] Making a request
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.
[edit] Example requests
- 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://lyricwiki.org/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:
[edit] Response Formats
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
[edit] Samples that use REST
- 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.
[edit] Documentation on each function/method
For details about the input and output of each function/method please refer to the SOAP's request/response documentation.
