IMSLP:OldAPI

Introduction

This page is the main manual page for accessing the old IMSLP API. See IMSLP:API for a description of the new IMSLP API.

IMSLP offers a simple Ruby script to access this API. Anyone interested in obtaining the script should e-mail User:Feldmahler with a description of the purpose for the request.

IMSLP-specific API

IMSLP has a separate API to query information not contained on work pages. The entry page is Special:IMSLPAPI.

General Usage Syntax: http://imslp.org/Special:IMSLPAPI/<return format>/<function>/<first double url-encoded arg>/<second double url-encoded arg>/<and so on>...

Note: There must be a trailing slash (/) after the function name if there are no arguments.

General Return Format: All return values are serialized using the PHP serialize() function. A string with the error is returned on failure, a non-string with the result on success.

Note: Any non-PHP implementation of the unserialize() function only needs to be able to unserialize the following: arrays, numbers, strings and booleans. See Ruby implementation below.

Return Format

• php - Serialize the return value using PHP's serialize() function.
• json - Serialize the return value in JSON.
• wddx - Serialize the return value in WDDX.

Supported Functions

lookup

• Description: Returns the index number and copyright status string of a list of file names.
• Arguments: A list of file names (each file name as a separate argument, as per General Usage Syntax above).
• Return: An Array containing an entry for each "file name" (regardless of whether the name is legitimate), indexed in the order the file name was passed to IMSLPLookup. Each entry consists of a separate Array with the following indexes:
  1. filename contains the canonical (processed) file name, which is not necessarily identical to the file name provided to IMSLPLookup
  2. index contains the IMSLP index of the file, or bool FALSE if the file name is bad or has not been submitted yet
  3. ctag contains a string representation of the copyright tagging status of the file, or bool FALSE if the file name is bad or has not been submitted yet
  4. crblock contains a description of the copyright block status, or bool FALSE if the file name is bad or has not been submitted yet. The possible block statuses are 'crblock' = [B], 'crblockus' = [TB], 'crblockeu' = (EU), and empty string = no block.

genretags

• Description: Returns the array used to resolve the genre tags.
• Arguments: None.
• Return: An Array in the format ( tag => [ list of categories ] ).
• Notes: The first category is usually the most descriptive category for the tag. (Technically speaking, it is the first category specified in MW:G.)

Simple PHP API Client

function query_imslp_api( $function, $args = array() )
{
    return unserialize( file_get_contents( "http://imslp.org/wiki/Special:IMSLPAPI/{$function}/" . implode( '/', array_map( 'rawurlencode', 
$args ) ) ) );
}

Ruby implementation of PHP's unserialize()

unserialize is the main function; do_uns is a helper function and should not be called directly.

def unserialize( string )
	string = StringIO.new( string )
	def string.read_until( char )
		val = ''
		while (c = self.read( 1 )) != char
			val << c
		end
		val
	end
	do_uns( string )
end

def do_uns( string )
	case (type = string.read(2)[0,1])
		when 'a' # associative array, a:length:{[index][value]...}
			val = {}
			string.read_until( '{' ).to_i.times { |i|
				key = do_uns( string ); val[key] = do_uns( string ) }
			string.read( 1 ) # skip the ending }
		when 's' # string, s:length:"data";
			len = string.read_until( ':' ).to_i + 3 # quotes, separator
			val = string.read( len )[1...-2] # read it, kill useless quotes
		when 'i' # integer, i:123
			val = string.read_until( ';' ).to_i
		when 'd' # double (float), d:1.23
			val = string.read_until( ';' ).to_f
		when 'N' # NULL, N;
			val = nil
		when 'b' # bool, b:0 or 1
			val = ( string.read(2)[0] == ?1 ? true : false )
		else
			raise TypeError, "Unable to unserialize type '#{type}'"
	end
	val
end