RESTful Integration: Part Zero

To kick this series off, lets start with something simple. The
least-common denominator for a
RESTful
service is one that sends and receives
POX. Obviously this is not
where we want to be when we finish this series, but it does give us a
place to start. I will be using Ruby on Rails as the platform for
the code examples since it has excellent support for REST concepts built
into the framework. I want to be able to concentrate on the problem of
integration without getting bogged down by technical minutiae in trying
to build these services using .NET or Java. Once I get some of this
working with Rails, maybe I will do a series on implementing this
integration architecture using other platforms. I am also going to
assume a working knowledge of Ruby and Rails. I will be focusing on
integration and will not be providing step-by-step directions on using
Rails. So without further ado, lets get started.

This first application will consist of a basic service that will accept
job quotations. So using Rails’ scaffolding generator, I created a
simple quotation service with three fields. (Customer, Status and Quote
Amount) As we continue through this series we will add more features to
this service, but this will be enough to get started. With our service
generated, we can proceed to set it up to receive an XML message using
an HTTP POST command. First we need to add a little bit of code to the
new method in the quotations controller.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
def new
@quotation = Quotation.new

respond_to do |format|
format.html # new.html.erb

format.xml {
quote = params[:quotation]
@quotation.customer = quote[:customer]
@quotation.quote_amount = quote[:quote_amount]
@quotation.status = quote[:status]
@quotation.save
render :xml => @quotation
}
end
end

This code snippet will parse the XML message and store using whatever
storage mechanism you have configured Rails to use. (On my system, it is
SQLite3) Our next step is to then test this. To do so, we will first
create an XML message with some test data.

1
2
3
4
5
6
<?xml version="1.0" encoding="UTF-8"?>
<quotation>
<customer>Rogue Technology</customer>
<quote -amount>50000.00</quote>
<status>New</status>
</quotation>

Next we will use curl to send the message to the service.

1
curl -H "Accept: text/xml" -H "Content-Type: text/xml" -d @quote.xml http://localhost:3000/quotations/new

Now that we have this much working lets take a look at where we are. We
have built a basic service that will accept an XML message and thanks to
the Rails framework, will happily return XML messages in a RESTful
manner. At the same time, we have some issues that will need to be
addressed. Our service does not use
HATEOAS
to present any sort of context information to clients. Plus, using
text/xml or application/xml does nothing to tell the client about the
format of the XML message our service is expecting to receive. Next time
we will look at setting up our service to use a custom media type that
better identifies what our service will be sending and receiving.