LyricWiki:REST

From LyricWiki

Contents 1 LyricWiki:REST 2 How to use the REST API 2.1 Making a request 2.1.1 Example requests 2.2 Response Formats 3 Samples that use REST 4 Documentation on each function/method

[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:

1. 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.
   1. getSong() - default if no 'func' is provided.
   2. 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).
   3. getHometown()
2. ... - 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.
3. fmt - Optional format of the response. See Response Formats below.

[edit] Example requests

• Get the lyrics to Tool's Schism in XML format:

  http://lyricwiki.org/api.php?func=getSong&artist=Tool&song=Schism&fmt=xml

• 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:

  http://lyricwiki.org/api.php?func=getSong&artist=Linkin_Park&fmt=html or better:

  http://lyricwiki.org/api.php?func=getArtist&artist=Linkin_Park&fmt=html or best:

  http://lyricwiki.org/api.php?func=getArtist&artist=Linkin_Park

[edit] Response Formats

The format of the response is specified by the 'fmt' parameter. This case-insensitive value defaults to 'html'.

1. HTML (default) - Lightly formatted lyrics result. Example HTML lyrics.
2. TEXT - Raw lyrics. Other fields are not returned. Example of just text lyrics.
3. XML - Light-weight XML version of the same values that the SOAP would return. Example of lyrics in xml.
4. 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.

• Rhapsolyric iPhone App