To send a file to a Rails application, using a RESTful XML API call, use the following XML snippet:

<field type="file" name="filename.ext" content-type="mime/type">
  base64-encoded file contents
</field>

The file contents should be base64 encoded, and may be encapsulated in a CDATA block:

<greeting type="file" name="greeting.txt" content-type="text/plain">
  <![CDATA[SGVsbG8gd29ybGQh]]>
</greeting>

You can test this by opening a console and feed the XML to Hash.from_xml:

>> greeting = <<-EOXML
    <greeting type="file" name="greeting.txt" content-type="text/plain">
      <![CDATA[SGVsbG8gd29ybGQh]]>
    </greeting>
  EOXML
 
>> data = Hash.from_xml(greeting)
=> {"greeting"=>#<StringIO:0x10617d9d0>}
>> data['greeting'].content_type
=> "text/plain"
>> data['greeting'].original_filename
=> "greeting.txt"
>> data['greeting'].read
=> "Hello world!"

Now you can handle files using your XML API just like you would use file uploads in your HTML forms.

I fixed bugs in the current libxml and nokogiri backends, and I added some new SAX-based backends for additional performance. My patches are already accepted by the Rails team, so everybody will enjoy fast and bug-free XML parsing in Rails 2.3.6 and eventually in Rails 3!

Performance

I have benchmarked the new backends using an 1.8 MB XML file. The REXML, LibXML and Nokogiri backends currently ship with Rails, but are horribly slow or are buggy. The ++ variants are my improved versions of these backends, and the SAX variants are completely written from scratch using a SAX-based parser.

                  user     system      total        real
REXML        17.170000   0.060000  17.230000 ( 17.297263)
LibXML        2.100000   0.100000   2.200000 (  2.217380)
LibXML++      0.530000   0.000000   0.530000 (  0.531034)
LibXMLSAX     0.630000   0.010000   0.640000 (  0.632472)
Nokogiri      5.280000   0.020000   5.300000 (  5.322575)
Nokogiri++    1.840000   0.020000   1.860000 (  1.872055)
NokogiriSAX   0.770000   0.000000   0.770000 (  0.778777)

As you can see, LibXML++ is the fastest backend, but NokogiriSAX comes close if you want to stick to Nokogiri.

No patience?

Don’t want to wait for the next Rails version for this speed up? You don’t have to: just put the appropriate backend file in the /lib/active_support/xml_mini/ folder of your Rails project, and set your backend accordingly in your environment:

ActiveSupport::XmlMini.backend = 'NokogiriSAX'

Happy coding in 2010!

The Floorplanner Flash application communicates with our servers to load and save projects and designs. The backend for this functionality used to be written in PHP. Eliminating this PHP application simplifies our server setup, eases development and reduces our maintenance burden. To rewrite this functionality in Rails, we decided to eat our own dogfood and use the REST API to load and save designs. Why reinvent the wheel?

However, while implementing the changes it the Flash application, we found that it did not work out of the box, because of some limitations in ActionScript. Note that we still use ActionScript 2, so some of these issues may not be relevant for ActionScript 3. In this post, we will detail what these issues are and how we overcame them.

Using a separate format

Our REST API uses the XML format supplied by Rails. Because we had to make some changes to make it work from ActionScript, we decided to add a distinct format that we could implement differently without altering the behavior of the default XML API. Adding a new format, called “flash” can be done in Rails by adding a MIME alias to your environment:

Mime::Type.register_alias "application/xml", :flash

Now we can send different responses based on this format:

respond_to do |format|
  format.xml   { ... } # default API behavior
  format.flash { ... } # do something different
end

HTTP status codes

REST APIs use HTTP status codes to return whether a call succeeded, and if not, why. Flash however uses the browser to perform HTTP requests. The browser only returns something to Flash if the request was successful. So, if an error code is used if a request failed together with some error messages, these error messages will not be delivered to Flash and cannot be displayed to the user. We resolved this by always sending the HTTP OK status.

respond_to do |format|
  format.xml   { render :xml => @project.errors, :status => 422 }
  format.flash { render :xml => XML.failure(@project.errors, 422) }
end

Our XML.failure method will return something like:

<failure status="422">
  <error on="name">A project should have a name!</error>
</failure>

Note that other HTTP success statuses than 200 work in Safari and Firefox, but not in Internet Explorer. So, never return a 201 (:created), because Internet Explorer will not send the result to Flash!

PUT and DELETE requests

REST-style APIs use HTTP PUT requests to alter objects and DELETE requests to destroy objects. Most browsers do not support these request type. It is not supported by ActionScript either, because Flash uses the browser to send the request.

To overcome this problem, these types of requests can be simulated in Rails by sending a _method parameter along with a POST request. Unfortunately, this does not work when calling the REST API. The POST request body cannot be used to send additional variables, because it is used for the XML payload.

We solved this issue by creating additional routes for POST requests to the update and destroy actions of our resource controllers. Our routes.rb file now looks like this:

  map.resources :projects, :member => { :update => :post, :destroy => :post }

These routes route to exactly the same methods as the default REST actions (ProjectsController#update and ProjectsController#destroy), so no additional code is needed. The following calls are now equivalent:

PUT    /projects/123.xml
POST   /projects/123/update.xml
POST   /projects/123/update.flash

DELETE /projects/123.xml
POST   /projects/123/destroy.xml
POST   /projects/123/destroy.flash

The result

It requires some stretching of the pure REST principles, but doing so is worth it: we can now reuse the code we use for our API to handle Flash application calls and we can eliminate the PHP backend.