xmlrpc-endpoint¶ ↑

Rails has native support for xmlrpc. Most people are familiar with the ‘xmlrpc/client’ library. The ‘xmlrpc/server’ library examples mostly make an assumption that you will run a standalone server.

xmlrpc-endpoint allows you to instead expose normal Rails controller methods via XMLRPC, tied to an xmlrpc endpoint route in your app.

Install

gem install xmlrpc-endpoint
config.gem "xmlrpc-endpoint" (inside environment.rb Rails::Initializer block)
          -- OR --
./script/plugin install git://github.com/wkoffel/xmlrpc-endpoint.git

Setup your environment

# set up a route to the controller action "xe_index" in your routes.rb file
# (this "xe_index" action will be created for you by the xmlrpc-endpoint, the route must point at 'xe_index' action to work)
# In a future release, xmlrpc-endpoint may support auto-generation of this route, and customization

map.connect 'api/xmlrpc', :controller => 'my_api_controller', :action => 'xe_index'

Add this code to your controller:

class MyApiController < ApplicationController
  exposes_xmlrpc_methods

  def hello_world
    puts "Hello XMLRPC."
  end
end

Then, pointing an XMLRPC client at the defined route, your normal controller actions will handle the requests.

require 'xmlrpc/client'
server = XMLRPC::Client.new2("http://localhost:3000/api/xmlrpc")
server.call("hello_world")

To use a custom namespace prefix on all exposed methods (for example, if using someone else’s specified protocol like MetaWeblog), declare a method_prefix:

class MyApiController < ApplicationController
  exposes_xmlrpc_methods :method_prefix => "metaWeblog."

  # This method will be exposed externally as "metaWeblog.newPost()"
  def newPost(blogid, username, password, struct, publish)
  ...
  end
end

Thanks to Nathan Crause for saving me some time on the details of avoiding the standalone server. nathan.crause.name/entries/programming/xlm-rpc-under-ruby-on-rails

Notes and Gotchas¶ ↑

• Be aware that Rails XMLRPC is finnicky about marshalling ‘nil’ values across the wire.

• To have an object marshalled correctly, you need to include XMLRPC::Marshallable in the object class, and be sure that all the instance variables are also marshallable.

• ActiveRecord objects hide their instance variables behind the single @attributes hash (confirm with activerecord_obj.instance_variables, you’ll see only two, @attributes and @attributes_cache). This means that AR objects might not end up in object format you’d expect if you simply include Marshallable. Be aware if you don’t own both ends of the API in question.

Note on Patches/Pull Requests¶ ↑

• Fork the project.

• Make your feature addition or bug fix.

• Add tests for it. This is important so I don’t break it in a future version unintentionally.

• Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)

• Send me a pull request. Bonus points for topic branches.

Copyright¶ ↑

Copyright © 2010 Will Koffel, released under the MIT license.