rbrainz 0.1.1 → 0.2.0

data/lib/rbrainz/webservice/query.rb

@@ -1,7 +1,9 @@
-# $Id: query.rb 31 2007-05-29 02:38:42Z phw $
-# Copyright (c) 2007, Philipp Wolfer
-# All rights reserved.
-# See LICENSE for permissions.
+# $Id: query.rb 147 2007-07-19 17:10:26Z phw $
+#
+# Author::    Philipp Wolfer (mailto:phw@rubyforge.org)
+# Copyright:: Copyright (c) 2007, Nigel Graham, Philipp Wolfer
+# License::   RBrainz is free software distributed under a BSD style license.
+#             See LICENSE[file:../LICENSE.html] for permissions.
 
 require 'rbrainz/webservice/webservice'
 require 'rbrainz/webservice/mbxml'
@@ -9,54 +11,339 @@ require 'rbrainz/webservice/mbxml'
 module MusicBrainz
   module Webservice
 
+    # A simple interface to the MusicBrainz web service.
+    # 
+    # This is a facade which provides a simple interface to the MusicBrainz
+    # web service. It hides all the details like fetching data from a server,
+    # parsing the XML and creating an object tree. Using this class, you can
+    # request data by ID or search the _collection_ of all resources
+    # (artists, labels, releases or tracks) to retrieve those matching given
+    # criteria. This document contains examples to get you started.
+    # 
+    # 
+    # == Working with Identifiers
+    # MusicBrainz uses absolute URIs as identifiers. For example, the artist
+    # 'Tori Amos' is identified using the following URI:
+    #   http://musicbrainz.org/artist/c0b2500e-0cef-4130-869d-732b23ed9df5
+    # 
+    # In some situations it is obvious from the context what type of 
+    # resource an ID refers to. In these cases, abbreviated identifiers may
+    # be used, which are just the _UUID_ part of the URI. Thus the ID above
+    # may also be written like this:
+    #   c0b2500e-0cef-4130-869d-732b23ed9df5
+    # 
+    # All methods in this class which require IDs accept both the absolute
+    # URI and the abbreviated form (aka the relative URI).
+    # 
+    # 
+    # == Creating a Query Object
+    # 
+    # In most cases, creating a Query object is as simple as this:
+    #   require 'rbrainz'
+    #   q = MusicBrainz::Webservice::Query.new
+    # 
+    # The instantiated object uses the standard Webservice class to
+    # access the MusicBrainz web service. If you want to use a different 
+    # server or you have to pass user name and password because one of
+    # your queries requires authentication, you have to create the
+    # Webservice object yourself and configure it appropriately.
+    # 
+    # This example uses the MusicBrainz test server and also sets
+    # authentication data:
+    #   require 'rbrainz'
+    #   service = MusicBrainz::Webservice::Webservice.new(
+    #     :host     => 'test.musicbrainz.org',
+    #     :username => 'whatever', 
+    #     :password => 'secret'
+    #   )
+    #   q = MusicBrainz::Webservice::Query.new(service)
+    # 
+    # 
+    # == Querying for Individual Resources
+    # 
+    # If the MusicBrainz ID of a resource is known, then the get_artist_by_id,
+    # get_label_by_id, get_release_by_id or get_track_by_id method can be used
+    # to retrieve it.
+    # 
+    # Example:
+    #   require 'rbrainz'
+    #   q = MusicBrainz::Webservice::Query.new
+    #   artist = q.get_artist_by_id('c0b2500e-0cef-4130-869d-732b23ed9df5')
+    #   puts artist.name
+    #   puts artist.sort_name
+    #   puts artist.type
+    #   
+    # _produces_:
+    #   Tori Amos
+    #   Amos, Tori
+    #   http://musicbrainz.org/ns/mmd-1.0#Person
+    # 
+    # This returned just the basic artist data, however. To get more detail
+    # about a resource, the _includes_ parameters may be used 
+    # which expect an ArtistIncludes, ReleaseIncludes, TrackIncludes or
+    # LabelIncludes object, depending on the resource type.
+    # It is also possible to use a Hash for the _includes_ parameter where it
+    # will then get automaticly wrapped in the appropriate includes class.
+    # 
+    # To get data about a release which also includes the main artist
+    # and all tracks, for example, the following query can be used:
+    #   require 'rbrainz'
+    #   q = MusicBrainz::Webservice::Query.new
+    #   release_id = '33dbcf02-25b9-4a35-bdb7-729455f33ad7'
+    #   release = q.get_release_by_id(release_id, :artist=>true, :tracks=>true)
+    #   puts release.title
+    #   puts release.artist.name
+    #   puts release.tracks[0].title
+    # 
+    # _produces_:
+    #   Tales of a Librarian
+    #   Tori Amos
+    #   Precious Things
+    # 
+    # Note that the query gets more expensive for the server the more
+    # data you request, so please be nice.
+    # 
+    # 
+    # == Searching in Collections
+    # 
+    # For each resource type (artist, release, and track), there is one
+    # collection which contains all resources of a type. You can search
+    # these collections using the get_artists, get_releases, and
+    # get_tracks methods. The collections are huge, so you have to
+    # use filters (ArtistFilter, ReleaseFilter, TrackFilter or LabelFilter)
+    # to retrieve only resources matching given criteria.
+    # As with includes it is also possible to use a Hash as the filter where
+    # it will then get wrapped in the appropriate filter class.
+    # 
+    # For example, If you want to search the release collection for
+    # releases with a specified DiscID, you would use get_releases:
+    #   require 'rbrainz'
+    #   q = MusicBrainz::Webservice::Query.new
+    #   results = q.get_releases(ReleaseFilter.new(:disc_id=>discId='8jJklE258v6GofIqDIrE.c5ejBE-'))
+    #   puts results[0].score
+    #   puts results[0].entity.title
+    # 
+    # _produces_:
+    #   100
+    #   Under the Pink
+    #   
+    # 
+    # The query returns a list of results in a ScoredCollection, 
+    # which orders entities by score, with a higher score
+    # indicating a better match. Note that those results don't contain
+    # all the data about a resource. If you need more detail, you can then
+    # use the get_artist_by_id, get_label_by_id, get_release_by_id, or
+    # get_track_by_id methods to request the resource.
+    # 
+    # All filters support the _limit_ argument to limit the number of
+    # results returned. This defaults to 25, but the server won't send
+    # more than 100 results to save bandwidth and processing power. In case
+    # you want to retrieve results above the 100 results limit you can use the
+    # _offset_ argument in the filters. The _offset_ specifies how many entries
+    # at the beginning of the collection should be skipped.
+    # 
     class Query
     
-      def initialize(webservice = nil)
+      # Create a new Query object.
+      # 
+      # You can pass a custom Webservice[link:classes/MusicBrainz/Webservice/Webservice.html]
+      # object. If none is given a default webservice will be used.
+      #
+      # If the constructor is called without arguments, an instance
+      # of WebService is used, preconfigured to use the MusicBrainz
+      # server. This should be enough for most users.
+      #
+      # If you want to use queries which require authentication you
+      # have to pass a Webservice instance where user name and
+      # password have been set.
+      #
+      # The _client_id_ option is required for data submission.
+      # The format is <em>'application-version'</em>, where _application_
+      # is your application's name and _version_ is a version
+      # number which may not include a '-' character.
+      #
+      # Available options:
+      # [:client_id] a unicode string containing the application's ID.
+      # [:factory]   A model factory. An instance of Model::DefaultFactory
+      #              will be used if none is given.
+      def initialize(webservice = nil, options={ :client_id=>nil, :factory=>nil })
+        Utils.check_options options, :client_id, :factory
         @webservice = webservice.nil? ? Webservice.new : webservice
+        @client_id  = options[:client_id] ? options[:client_id] : nil
+        @factory    = options[:factory] ? options[:factory] : nil
       end
       
-      def get_artist_by_id(id, include = nil)
-        return get_entity_by_id(Model::Artist.entity_type, id, include)
+      # Returns an artist.
+      # 
+      # The parameter _includes_ must be an instance of ArtistIncludes
+      # or a options hash as expected by ArtistIncludes.
+      # 
+      # If no artist with that ID can be found, include contains invalid tags
+      # or there's a server problem, and exception is raised.
+      # 
+      # Raises:: ConnectionError, RequestError, ResourceNotFoundError, ResponseError
+      def get_artist_by_id(id, includes = nil)
+        includes = ArtistIncludes.new(includes) unless includes.nil? || includes.is_a?(ArtistIncludes)
+        return get_entity_by_id(Model::Artist.entity_type, id, includes)
       end
       
-      # TODO: implement
+      # Returns artists matching given criteria.
+      # 
+      # The parameter _filter_ must be an instance of ArtistFilter
+      # or a options hash as expected by ArtistFilter.
+      # 
+      # Raises:: ConnectionError, RequestError, ResponseError
       def get_artists(filter)
-        raise NotImplementedError.new
+        filter = ArtistFilter.new(filter) unless filter.nil? || filter.is_a?(ArtistFilter)
+        return get_entities(Model::Artist.entity_type, filter)
       end
       
-      def get_release_by_id(id, include = nil)
-        return get_entity_by_id(Model::Release.entity_type, id, include)
+      # Returns an release.
+      # 
+      # The parameter _includes_ must be an instance of ReleaseIncludes
+      # or a options hash as expected by ReleaseIncludes.
+      # 
+      # If no release with that ID can be found, include contains invalid tags
+      # or there's a server problem, and exception is raised.
+      # 
+      # Raises:: ConnectionError, RequestError, ResourceNotFoundError, ResponseError
+      def get_release_by_id(id, includes = nil)
+        includes = ReleaseIncludes.new(includes) unless includes.nil? || includes.is_a?(ReleaseIncludes)
+        return get_entity_by_id(Model::Release.entity_type, id, includes)
       end
       
-      # TODO: implement
+      # Returns releases matching given criteria.
+      # 
+      # The parameter _filter_ must be an instance of ReleaseFilter
+      # or a options hash as expected by ReleaseFilter.
+      # 
+      # Raises:: ConnectionError, RequestError, ResponseError
       def get_releases(filter)
-        raise NotImplementedError.new
+        filter = ReleaseFilter.new(filter) unless filter.nil? || filter.is_a?(ReleaseFilter)
+        return get_entities(Model::Release.entity_type, filter)
       end
       
-      def get_track_by_id(id, include = nil)
-        return get_entity_by_id(Model::Track.entity_type, id, include)
+      # Returns an track.
+      # 
+      # The parameter _includes_ must be an instance of TrackIncludes
+      # or a options hash as expected by TrackIncludes.
+      # 
+      # If no track with that ID can be found, include contains invalid tags
+      # or there's a server problem, and exception is raised.
+      # 
+      # Raises:: ConnectionError, RequestError, ResourceNotFoundError, ResponseError
+      def get_track_by_id(id, includes = nil)
+        includes = TrackIncludes.new(includes) unless includes.nil? || includes.is_a?(TrackIncludes)
+        return get_entity_by_id(Model::Track.entity_type, id, includes)
       end
       
-      # TODO: implement
+      # Returns tracks matching given criteria.
+      # 
+      # The parameter _filter_ must be an instance of TrackFilter
+      # or a options hash as expected by TrackFilter.
+      # 
+      # Raises:: ConnectionError, RequestError, ResponseError
       def get_tracks(filter)
-        raise NotImplementedError.new
+        filter = TrackFilter.new(filter) unless filter.nil? || filter.is_a?(TrackFilter)
+        return get_entities(Model::Track.entity_type, filter)
       end
       
-      def get_label_by_id(id, include = nil)
-        return get_entity_by_id(Model::Label.entity_type, id, include)
+      # Returns an label.
+      # 
+      # The parameter _includes_ must be an instance of LabelIncludes
+      # or a options hash as expected by LabelIncludes.
+      # 
+      # If no label with that ID can be found, include contains invalid tags
+      # or there's a server problem, and exception is raised.
+      # 
+      # Raises:: ConnectionError, RequestError, ResourceNotFoundError, ResponseError
+      def get_label_by_id(id, includes = nil)
+        includes = LabelIncludes.new(includes) unless includes.nil? || includes.is_a?(LabelIncludes)
+        return get_entity_by_id(Model::Label.entity_type, id, includes)
       end
       
-      # TODO: implement
+      # Returns labels matching given criteria.
+      # 
+      # The parameter _filter_ must be an instance of LabelFilter
+      # or a options hash as expected by LabelFilter.
+      # 
+      # Raises:: ConnectionError, RequestError, ResponseError
       def get_labels(filter)
-        raise NotImplementedError.new
+        filter = LabelFilter.new(filter) unless filter.nil? || filter.is_a?(LabelFilter)
+        return get_entities(Model::Label.entity_type, filter)
       end
       
-      private
+      # Returns information about a MusicBrainz user.
+      # 
+      # You can only request user data if you know the user name and password
+      # for that account. If username and/or password are incorrect, an
+      # AuthenticationError is raised.
+      # 
+      # See the example in Query on how to supply user name and password.
+      # 
+      # Raises:: ConnectionError, RequestError, AuthenticationError, ResponseError
+      def get_user_by_name(name)
+        xml = @webservice.get(:user, :filter => UserFilter.new(name))
+        collection = MBXML.new(xml).get_entity_list(:user, Model::NS_EXT_1)
+        unless collection and collection.size > 0
+          raise ResponseError("response didn't contain user data")
+        else
+          return collection[0].entity
+        end
+      end
+      
+      # Submit track to PUID mappings.
+      #
+      # The <em>tracks2puids</em> parameter has to be a dictionary, with the
+      # keys being MusicBrainz track IDs (either as absolute URIs or
+      # in their 36 character ASCII representation) and the values
+      # being PUIDs (ASCII, 36 characters).
+      #
+      # Note that this method only works if a valid user name and
+      # password have been set. If username and/or password are incorrect,
+      # an AuthenticationError is raised. See the example in Query on
+      # how to supply authentication data.
+      #
+      # Raises:: ConnectionError, RequestError, AuthenticationError
+      def submit_puids(tracks2puids)
+        raise RequestError, 'Please supply a client ID' unless @client_id
+        params = [['client', @client_id.to_s]] # Encoded as utf-8
+
+        tracks2puids.each {|track_id, puid| params << ['puid', track_id + ' ' + puid ]}
+
+        @webservice.post('track', :querystring=>params)
+      end
+      
+      private # ----------------------------------------------------------------
       
       # Helper method which will return any entity by ID.
-      def get_entity_by_id(entity_type, id, include)
-        xml = @webservice.get(entity_type, id, :include => include)
-        return MBXML.new(xml).get_entity(entity_type)
+      # 
+      # Raises:: ConnectionError, RequestError, ResourceNotFoundError, ResponseError
+      def get_entity_by_id(entity_type, id, includes)
+        stream = @webservice.get(entity_type, :id => id, :include => includes)
+        begin
+          entity = MBXML.new(stream, @factory).get_entity(entity_type)
+        rescue MBXML::ParseError => e
+          raise ResponseError.new(e.to_s)
+        end
+        unless entity
+          raise ResponseError.new("server didn't return #{entity_type.to_s} with the MBID #{id.to_s}")
+        else
+          return entity
+        end
+      end
+      
+      # Helper method which will search for the given entity type.
+      # 
+      # Raises:: ConnectionError, RequestError, ResponseError
+      def get_entities(entity_type, filter)
+        stream = @webservice.get(entity_type, :filter => filter)
+        begin
+          collection = MBXML.new(stream, @factory).get_entity_list(entity_type)
+        rescue MBXML::ParseError => e
+          raise ResponseError.new(e.to_s)
+        end
+        return collection
       end
       
     end

data/lib/rbrainz/webservice/webservice.rb

@@ -1,54 +1,107 @@
-# $Id: webservice.rb 36 2007-05-29 18:43:36Z phw $
-# Copyright (c) 2007, Philipp Wolfer
-# All rights reserved.
-# See LICENSE for permissions.
+# $Id: webservice.rb 148 2007-07-19 17:26:33Z phw $
+#
+# Author::    Philipp Wolfer (mailto:phw@rubyforge.org)
+# Copyright:: Copyright (c) 2007, Nigel Graham, Philipp Wolfer
+# License::   RBrainz is free software distributed under a BSD style license.
+#             See LICENSE[file:../LICENSE.html] for permissions.
 
 require 'rbrainz/webservice/includes'
 require 'rbrainz/webservice/filter'
 require 'net/http'
+require 'stringio'
 
 module MusicBrainz
   module Webservice
 
+    # An interface all concrete web service classes have to implement.
+    # 
+    # All web service classes have to implement this and follow the method
+    # specifications.
     class IWebservice
       
-      # Query the Webservice with HTTP GET.
-      # Must be implemented by the concrete webservices.
-      def get(entity, id, options = {:include => nil, :filter => nil, :version => 1})
-        raise Exception.new('Called abstract method.')
+      # Query the web service.
+      # 
+      # This method must be implemented by the concrete webservices and
+      # should return an IO object on success.
+      # 
+      # Options:
+      # [:id]      A MBID if querying for a single ressource.
+      # [:include] An include object (see AbstractIncludes).
+      # [:filter]  A filter object (see AbstractFilter).
+      # [:version] The version of the webservice to use. Defaults to 1.
+      def get(entity_type, options={ :id=>nil, :include=>nil, :filter=>nil, :version=>1 })
+        raise NotImplementedError.new('Called abstract method.')
       end
       
-      # Query the Webservice with HTTP POST.
-      # Must be implemented by the concrete webservices.
-      # TODO: Specify and implement in Webservice.
-      def post
+      # Submit data to the web service.
+      #
+      # This method must be implemented by the concrete webservices and
+      # should return an IO object on success.
+      # 
+      # Options:
+      # [:id]      A MBID if querying for a single ressource.
+      # [:querystring] A string containing the data to post.
+      # [:version] The version of the webservice to use. Defaults to 1.
+      def post(entity_type, options={ :id=>nil, :querystring=>[], :version=>1 })
         raise NotImplementedError.new('Called abstract method.')
       end
       
     end
     
-    # Webservice class to query the default MusicBrainz server.
-    # TODO: Implement authorization.
+    # An interface to the MusicBrainz XML web service via HTTP.
+    # 
+    # By default, this class uses the MusicBrainz server but may be configured
+    # for accessing other servers as well using the constructor. This implements
+    # IWebService, so additional documentation on method parameters can be found
+    # there.
     class Webservice < IWebservice
     
       # Timeouts for opening and reading connections (in seconds)
       attr_accessor :open_timeout, :read_timeout
     
-      def initialize(options = {:host => nil, :port => nil, :path_prefix => nil})
+      # If no options are given the default MusicBrainz webservice will be used.
+      # User authentication with username and password is only needed for some
+      # services. If you want to query an alternative webservice you can do so
+      # by setting the appropriate options.
+      # 
+      # Available options:
+      # [:host] Host, defaults to 'musicbrainz.org'.
+      # [:port] Port, defaults to 80.
+      # [:path_prefix] The path prefix under which the webservice is located on
+      #                the server. Defaults to '/ws'.
+      # [:username] The username to authenticate with.
+      # [:password] The password to authenticate with.
+      # [:user_agent] Value sent in the User-Agent HTTP header. Defaults to 'rbrainz/0.2'
+      def initialize(options={ :host=>nil, :port=>nil, :path_prefix=>'/ws', :username=>nil, :password=>nil, :user_agent=>'rbrainz/0.2' })
+        Utils.check_options options, :host, :port, :path_prefix, :username, :password, :user_agent
         @host = options[:host] ? options[:host] : 'musicbrainz.org'
         @port = options[:port] ? options[:port] : 80
         @path_prefix = options[:path_prefix] ? options[:path_prefix] : '/ws'
+        @username = options[:username]
+        @password = options[:password]
+        @user_agent = options[:user_agent] ? options[:user_agent] : 'rbrainz/0.2'
         @open_timeout = nil
         @read_timeout = nil
       end
     
       # Query the Webservice with HTTP GET.
       # 
-      # Raises: +RequestError+, +ResourceNotFoundError+, +AuthenticationError+,
-      # +ConnectionError+ 
-      def get(entity, id, options = {:include => nil, :filter => nil, :version => 1})
-        url = URI.parse(create_uri(entity, id, options))
+      # Returns an IO object on success.
+      # 
+      # Options:
+      # [:id]      A MBID if querying for a single ressource.
+      # [:include] An include object (see AbstractIncludes).
+      # [:filter]  A filter object (see AbstractFilter).
+      # [:version] The version of the webservice to use. Defaults to 1.
+      # 
+      # Raises:: RequestError, ResourceNotFoundError, AuthenticationError,
+      #          ConnectionError 
+      # See:: IWebservice#get
+      def get(entity_type, options={ :id=>nil, :include=>nil, :filter=>nil, :version=>1 })
+        Utils.check_options options, :id, :include, :filter, :version
+        url = URI.parse(create_uri(entity_type, options))
         request = Net::HTTP::Get.new(url.request_uri)
+        request['User-Agent'] = @user_agent
         connection = Net::HTTP.new(url.host, url.port)
         
         # Set timeouts
@@ -57,9 +110,16 @@ module MusicBrainz
         
         # Make the request
         begin
-          response = connection.start {|http|
-            http.request(request)
-          }
+          response = connection.start do |http|
+            response = http.request(request)
+            if response.is_a?(Net::HTTPUnauthorized) && @username && @password
+              request = Net::HTTP::Get.new(url.request_uri)
+              request['User-Agent'] = @user_agent
+              request.digest_auth @username, @password, response
+              response = http.request(request)
+            end
+            response
+          end
         rescue Timeout::Error, Errno::ETIMEDOUT
           raise ConnectionError.new('%s timed out' % url.to_s)
         end
@@ -71,23 +131,100 @@ module MusicBrainz
           raise AuthenticationError.new(url.to_s)
         elsif response.is_a? Net::HTTPNotFound # 404
           raise ResourceNotFoundError.new(url.to_s)
+        elsif response.is_a? Net::HTTPForbidden 
+          raise AuthenticationError.new(url.to_s)
         elsif not response.is_a? Net::HTTPSuccess
           raise ConnectionError.new(response.class.name)
         end
         
-        return response.body
+        return ::StringIO.new(response.body)
+      end
+      
+      # Send data to the web service via HTTP-POST.
+      #
+      # Note that this may require authentication. You can set
+      # user name, password and realm in the constructor.
+      #
+      # Returns an IO object on success.
+      #
+      # Options:
+      # [:id]      A MBID if querying for a single ressource.
+      # [:querystring] A string containing the data to post.
+      # [:version] The version of the webservice to use. Defaults to 1.
+      #
+      # Raises:: ConnectionError, RequestError, AuthenticationError, 
+      #          ResourceNotFoundError
+      #
+      # See:: IWebservice#post
+      def post(entity_type, options={:id=>nil, :querystring=>[], :version=>1})
+        Utils.check_options options, :id, :querystring, :version
+        url = URI.parse(create_uri(entity_type, options))
+        request = Net::HTTP::Post.new(url.request_uri)
+        request['User-Agent'] = @user_agent
+        request.set_form_data(options[:querystring])
+        connection = Net::HTTP.new(url.host, url.port)
+        
+        # Set timeouts
+        connection.open_timeout = @open_timeout if @open_timeout
+        connection.read_timeout = @read_timeout if @read_timeout
+        
+        # Make the request
+        begin
+          response = connection.start do |http|
+            response = http.request(request)
+            
+            if response.is_a?(Net::HTTPUnauthorized) && @username && @password
+              request = Net::HTTP::Post.new(url.request_uri)
+              request['User-Agent'] = @user_agent
+              request.digest_auth @username, @password, response
+              request.set_form_data(options[:querystring])
+              response = http.request(request)
+            end
+            response
+          end
+        rescue Timeout::Error, Errno::ETIMEDOUT
+          raise ConnectionError.new('%s timed out' % url.to_s)
+        end
+        
+        # Handle response errors.
+        if response.is_a? Net::HTTPBadRequest # 400
+          raise RequestError.new(url.to_s)
+        elsif response.is_a? Net::HTTPUnauthorized # 401
+          raise AuthenticationError.new(url.to_s)
+        elsif response.is_a? Net::HTTPNotFound # 404
+          raise ResourceNotFoundError.new(url.to_s)
+        elsif response.is_a? Net::HTTPForbidden 
+          raise AuthenticationError.new(url.to_s)
+        elsif not response.is_a? Net::HTTPSuccess
+          raise ConnectionError.new(response.class.name)
+        end
+        
+        return ::StringIO.new(response.body)
       end
       
       private # ----------------------------------------------------------------
       
       # Builds a request URI for querying the webservice.
-      def create_uri(entity, id, options = {:include => nil, :filter => nil, :version => 1})
+      def create_uri(entity_type, options = {:id => nil, :include => nil, :filter => nil, :version => 1})
         # Make sure the version is set
         options[:version] = 1 if options[:version].nil?
         
         # Build the URI
-        uri  = 'http://%s:%d%s/%d/%s/%s?type=%s' %
-               [@host, @port, @path_prefix, options[:version], entity, id.uuid, 'xml']
+        if options[:id]
+          # Make sure the id is a MBID object
+          id = options[:id]
+          unless id.is_a? Model::MBID
+            id = Model::MBID.parse(id, entity_type)
+          end
+        
+          uri = 'http://%s:%d%s/%d/%s/%s?type=%s' %
+                [@host, @port, @path_prefix, options[:version],
+                 entity_type, id.uuid, 'xml']
+        else
+          uri = 'http://%s:%d%s/%d/%s/?type=%s' %
+                [@host, @port, @path_prefix, options[:version],
+                 entity_type, 'xml']
+        end
         uri += '&' + options[:include].to_s unless options[:include].nil?
         uri += '&' + options[:filter].to_s unless options[:filter].nil?
         return uri
@@ -96,4 +233,4 @@ module MusicBrainz
     end
     
   end
-end
+end