SOAP - A XML based server side API (Version 2.1)
Updated 2002-10-14
How does SOAP work?

SOAP (Simple Object Access Protocol) is a very simple and easy implementable protocol written for the Lyrictracker project. The whole protocol is based on the HTTP protocol and uses the HTTP FORM and GET commands to exchange data with the database server. It is virtually possible to connect any application independently of the platform to search and get song lyrics from the database.
Since this protocol builds up on the XML format, you will need an XML parser for your programming language.

Please note that the official SOAP definition in AppleScript has nothing to do with this. Well, not much at least.

Since we are already working on support for chords, given changes will be made shortly to the protocol. Please note that the current given definition won't change but attributes may be added.

What is the URL of the API?

All requests of the clients go to the one script that handles requests and converts them to the XML before it returns the information to the client.
You find the script at:

http://lyrictracker.com/soap.php

You may either use the POST command (recommed) or the GET command to send parameters to the server. To encode characters please use the ISO-8859-1 (Latin-1) encoding.

Request Basics

Here is a list of parameters that have to be included within every request your client makes to the server:

Parameter Name Description
act The action identifier for the current request. This tells the server what your client wants him to do. Please see the sections below for more informations.

If this identifier is not given, the server will return a simple "kNO_ACTION_ERR" in the HTTP body.
cln The name handle for of your client. Please contact Das-L Technologies to get a free handle for your client.

If this identifier is not given, the server will return a simple "kNO_IDENTIFIER_ERR" in the HTTP body.
clv The version of your client. On Macintosh it should be the 'Long Version' of your application.

If this identifier is not given, the server will return a simple "kNO_IDENTIFIER_ERR" in the HTTP body.

Searching the database and receiving results

To tell the server to query the database for given information you have to use the following RS (Request Specification). The XML returned by the server is described below.

Parameter Name Description
act Action handler for this type of request is query.
ar Partial or complete name of the song artist.
ti Partial or complete song title.
al (Optional) Partial or complete name of the album.
co (Optional) Partial or complete name of the composer(s).
yr (Optional) The year of the release of the given song. Format is YYYY (e.g. 1998)
txt (Optional) Part of the song text itself.
and If any value is given ("1" or "true") the server will query the parameters with the logical AND operator.

Server Reply

In the following example we searched with the following parameters: ar = "Janet Jackson" and ti = "gone".

<?xml version="1.0"?>
<results count="3">

    <result id="MzMx" artist="38 Special" title="After The Fire is Gone" album="" year="" views="" composer=""/>
    <result id="Njk5" artist="Bryan Adams" title="Long Gone" album="" year="" views="" composer=""/>
    <result id="MTk3MA==" artist="Pennywise" title="Gone" album="" year="" views="" composer=""/>

</xml>
Returning the lyric from the server
To return the text of a lyric from the database server you have to call the API with th following parameters and you will receive the lyrictext directly in the HTTP response body.

Parameter Name Description
act Action handler for this type of request is detail.
id The ID of the lyric which has been returned in the result list as XML attribute id.

Server Reply

The server will reply the lyric's text or in case of an error, the string "ERROR 1".
Submitting song lyrics to the database
In some cases you might want to let the users submit song lyrics to the database. For this purpose you have to use the following RS and submit the information to the server using a POST HTTP command.

Parameter Name Description
act Action handler for this type of request is submit.
un The username of the user who submits the lyric.
up The password of the user who submits the lyric.
ar The name of the song's artist.
ti The name of the song's title.
al (Optional) The name of the song's album.
co (Optional) The name of the composer(s). If more than one, seperated by ", " (comma-space).
yr (Optional) The year of the release of the song. Format is YYYY (e.g. 1998).
txt The song text.
info (Optional) Additional information to the song lyric. For example the URL to the website of the song's artist, or copyright information.
mwlid (Optional) The ID of the MWL request. See next section for more information.

Server Replies

If everything goes right, the server will return a simple "OK" in the body of the response. If you get an "ERROR 1" the username or the password are incorrect and you have to ask the user to try again.
Receiving the MWL (Most Wanted Lyrics) list from the server
The Lyrictracker database supports a system that lets users request lyrics. This system - called MWL - allows to notify users if a given lyric got added to the database. To fill a MWLreq (MWL Request) you have to add the id of the given WML entry to the submit method in the mwlid parameter (see above).

Parameter Name Description
act Action handler for this type of request is mwl-list.

Server Reply

<?xml version="1.0"?>
<mwllist>

    <mwl id="6" artist="Janet Jackson" title="Got Till It\'s Gone" dots="159"/>
    <mwl id="7" artist="Michael Jackson" title="Thriller" dots="244"/>
    <mwl id="8" artist="Smile.DK" title="Butterfly" dots="120"/>
</mwllist>