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).
- ... - 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.
- 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:
- (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).
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
- 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.