The last couple of weeks we’ve been working on a big integration project. The largest real estate portal of The Netherlands, Funda, uses Floorplanner to deliver interactive floor plans to their clients. They use our API’s to seamlessly integrate the Floorplanner into their back end system and front end website.

One of our API’s is our RESTful web service. With it one can manage users, project, floors, designs etc. We set up a whole testing suite around it, but every now and then I wanted to test a single method by hand. For this I used the command line tool cURL which looks something like this (getting all users):

curl -H "Content-Type: application/xml" 
-u "username:password" 
-X GET https://floorplanner.com/users.xml

It works, but it’s kind of a hassle. One day Michel showed me HTTP Client:

A Mac OS X Leopard developer tool for debugging HTTP services by graphically creating & inspecting complex HTTP messages.

HTTP Client makes testing a web service by hand much easier. You can select any REST method you need from a pull down menu. Setting up your header is done by a few mouse clicks and the result is nicely formatted.

The only thing that didn’t seem to work out of the box was Basic HTTP Authentication. I found a workaround for this: add the authorization to the header myself. To do this use “Authorization” as header name. For the header value you have to encode the username and password with Base64 with a “:” as separator. For example in PHP: base64_encode(username:password). There are also a couple of websites around where you can encode a string to Base64. When you have the encoded string, you can add “Basic encoded string here” as a header value and you’re ready to roll.

We have been working hard to implement an XML-based REST-style API for Floorplanner and some of our partners are using it already to access their users and plans. We now have started to use this API ourselves.

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.