ben robison

Howto: Put WSDL on Rails

Why do I love Rails so much? Because there is so much to love! Who ever dreamed that creating web services could be so simple? Where other frameworks can consume them very simply, Rails defines simplicity when it comes to creating them. Consuming them is easy as well, but it’s on the creation side that Rails really stands out from the competition. So how do you do it?

First off, let me say that my inexperience in web services means that I’m far from a subject matter expert. I can however follow simple instructions, and I found a beautiful set over at the SOA Ranch. This is a 3 part series, though more are supposedly coming. I hope these articles continue to be published, but I have my doubts as the most recent articles are nearly 6 months old now. The first one I found was part 3 part 2.5 in the series, and you can follow the links back to part 1 & part 2.

So let’s get down to business. I’ll make the assumption that you’ve got a working Rails environment. For Mac users, the latest version of Locomotive has everything you need for creating web services. For everyone else you’ll have to make your Rails environment the old fashioned way, although you can look forward to Rubuntu soon. We’re going to create a very simple web service that accepts a string, changes it a bit and returns a string.

First create yourself a new application

rails WebServiceProvider

Then you’ll want to open your application in your favorite Rails editor. Then we need to generate your web service.

./script/generate web_service Manipulation manipulate

This will create an API file for us to define our web service’s interface. It also creates a controller for us to use, and then a test file for us to use later (we won’t get to scripted testing in this article, although we will test it manually to prove that it works).

Now open up your manipulation_api.rb file in app/apis. You’ll see the following line of code that is the beginnings of our string manipulating web service.

api_method :manipulate

We’ll need to define parameters and data types for our method like so:

api_method :manipulate, :expects => [:string], :returns => [:string]

There are many data types that can be used here, but we’re keeping things easy for now. Now we’ll go look at the ManipulationController at app/controllers/manipulation_controller.rb. Because we followed the standard Rails naming conventions the mapping of the web service to the controller is already done, but if we hadn’t, this mapping can be done explicitly by adding the following to our controller.

web_service_api ManipulationApi

We can also give our web service a different name with the wsdl_service_name directive

wsdl_service_name 'Manipulation'

Notice also that in the controller is where we define all our logic for what happens with the parameters being passed in by our web service consumer. the manipulate method has already been created for us, so we simply need to tell our method to accept a string, perform our logic, and return another string.

Again we’ll keep things simple.

def manipulate(terms)
return "Yeah! " + terms + "!"
end


Now for all intents and purposes, our web service has been coded. We’ll add one more line to our controller that will generate a web front-end for the service so we can go see how it looks on the browser end. Just add the following line to your controller.

web_service_scaffold :invoke

Now let’s turn on the server and see how things look. Back at the terminal type

./script/server

Open your browser and point it to http://localhost:3000/Manipulation/invoke. This shows us the web view of our API. Follow the manipulate link to see the auto-generated web form that will show us what our service looks like. Type your message into Param0 box and click the invoke button to see all your beautiful web service XML. Another important point for those wishing to consume your web service is that Rails is automatically generating your wsdl for you. You can see how this works by checking the routes.rb file in app/config but just know that visiting http://localhost:3000/Manipulation/service.wsdl you can see the WSDL file that others will need to use your web service. You can use something besides service.wsdl by editing your routes.rb file appropriately.

Now this is obviously a simple example, but it illustrates the basic steps and important points. You probably wouldn’t have much use for a web service that adds the word “Yeah” and a few exclamation points to some user-input, but if we were doing this in the context of a real web application, you can start to imagine the possibilities available in your controller if you’ve got a dynamic database-driven application to work with. You can add other methods to your API, define the param and return types there, then define the logic in the controller in the appropriate method. Once you get the basics down, you’re on your way and the sky is the limit. Good luck developing your first piece of the Web 2.0.