The Python Web Services Developer: Part 3

Continuing their example of a Web service for storing and managing software, Uche Ogbuji and Mike Olson illustrate how to update the repository using SOAP messages and how to advertise it as a Web service.

We began presenting an example of a software repository in part 2 of this column, illustrating how a lot of the heavy lifting of data and metadata management could be made much simpler by using available Web tools and open Web standards such as XML, XSLT, and RDF. Since building the core of the software repository was so simple, we now have time to contemplate how to represent this in a Web service.

In this article, we will look at ways of adding content to the software repository using HTTP POST and SOAP. Also, we’ll look at a SD description of the resulting Web service and how 4Suite Server can help expose this. You will want to be familiar with the work from part 2 as well as with HTML forms and the Hypertext Transport Protocol (HTTP) protocol (see Resources).

{mospagebreak title=Article&toc=1} Software by Post

To begin with we should look at updates using simple HTTP POST. This can serve as a means for both human contributors and software agents to provide updates, the former by way of a browser form.

Start by making sure that the software repository core is set up using the steps we explained in part 2. Unfortunately, there’s a twist. The last article was based on 4Suite Server version 0.10.2, but since then we released version 0.11.0, with significant improvements. See Resources for an update to the last article that covers the 0.11.0 release.

Let’s say the form for contributors to use in adding entries to the repository is as in Figure 1. This corresponds to the HTML in Listing 1.

Figure 1: Form for Adding New Software to the Repository

4Suite Server allows us to set up an XSL transform to handle POST requests such as this form generates, creating a new document that is added to the XML repository. The XSL transform we use for the purpose of adding an entry to the software repository is in Listing 2.

Theaction attribute of the form element in our HTML source is interpreted with the document at the path in the URI as the source, and thetemplate-xslt argument is interpreted as the XSL transform to use for generating the new document.

Listing 2: XSLT transform to turn HTTP POST data into a new XML document

<?xml version=”1.0″?>
  <xsl:param name=’title’/>
  <xsl:param name=’creator’/>
  <xsl:param name=’home’/>
  <xsl:param name=’version’/>
  <xsl:param name=’description’/>
  <xsl:template match=”/”>
  <Software rdf:ID=”{$title}”>
    <dc:Title><xsl:value-of select=’$title’/></dc:Title>
    <dc:Creator><xsl:value-of select=’$creator’/></dc:Creator>
    <dc:Description><xsl:value-of select=’$description’/></dc:Description>
    <CurrentVersion><xsl:value-of select=’$version’/></CurrentVersion>
    <Home rdf:resource=”{$home}”/>

The first thing to note is the group of parameters such astitle andcreator. These are automatically set by the server to the values from the form elements of the same name, which become HTTP POST query arguments. These parameters can then be used to craft the output using all the tools XSLT places at our disposal. As you can see, the transform is creating a software description document in the form we introduced in the first part of this series. We omitted some optional fields for simplicity.

Finally, observe theftext:set-post-template-params extension element at the end of the transform. This is a special extension set up by the server which allows you to set such important parameters as the URI of the document to be added, its document definition and the URI to be used by the server to generate the HTML to be sent in response to the HTTP POST (this is, for instance, the HTML that would appear in the browser after the “Submit” button was clicked to submit an entry).

The steps involved are briefly outlined here:

  1. Create a container and give universal read access to it.
  2. Create a document for the HTTP POST operation.
  3. Create the XSLT template.
  4. Create the submission response document.
  5. Create the container to store the output.

To try this yourself, first create an appropriate container and grand universal read access to it:

Listing 3a

$ 4ss create container /softrepo
$ 4ss set acl –world-read /softrepo

Then create a simple dummy document (just “<null/>”) as the HTTP POST target. For example:

Listing 3b

$ 4ss create document – BASE_XML /softrepo/submit-new-software-entry
$ 4ss set acl –world-read /softrepo/submit-new-software-entry

If you specify “-” as the source for the XML document, the command will read the XML source from standard input. Next, create the template XSLT document, as shown below:

Listing 3c

$ 4ss create document submit-entry.xslt BASE_XSLT /softrepo/submit-entry.xslt
$ 4ss set acl –world-read softrepo/submit-entry.xslt

Now create the submission response document as follows:

Listing 3d

$ 4ss create document – BASE_XML softrepo/thanks.xhtml
<?xml version=’1.0′ encoding=’UTF-8′?>
“-//W3C//DTD XHTML 1.0 Strict//EN” “DTD/xhtml1-strict.dtd”>
<html xmlns=’’>
<title>Thanks for your submission</title>
  <p>Thanks for your submission to the software repository.</p>
$ 4ss set acl –world-read softrepo/thanks.xhtml

Finally, create the container where submitted software records will go. This one must be world-writable in order for the documents to be added by anonymous users. See listing 3e.

Listing 3e

$ 4ss create container softrepo/incoming
$ 4ss set acl –world-write softrepo/incoming

Once this is set up, people can enter the data into a form, or software agents can enter the data using HTTP libraries in the language of choice. There is, however, an alternative growing in popularity for software-to-software access of data, without involving humans.

Software on a Rope
4Suite Server implements the basic SOAP API, which we can use as the basis of our software repository Web service.

Listing 4 is a simple Python command-line program that adds a software entry file using the direct SOAP API. Note the special encoding style used in the direct 4Suite Server API. This encoding basically consists of an element representing the method invocation and attributes representing the parameters, and in some cases a body containing a document that serves as a parameter. Other than that, Listing 4 is pretty straightforward code to construct an XML representing a SOAP request document from command-line parameters — put this into an HTTP request, send it off and listen for the response.

Listing 4: A Python Program to Send a SOAP Request According to the Core API

import sys, string, httplib, base64, mimetools
    <ft:Create doc-def-name=”%s” uri=”%s”>
#define the function
def AddSoftwareFromFile(entry, docdef, uri):
    body = BODY_TEMPLATE%(docdef, uri, base64.encodestring(entry))
    blen = len(body)
    requestor = httplib.HTTP(SERVER_ADDR, SERVER_PORT)
    requestor.putrequest(‘POST’, ‘/soap-handler’)
    requestor.putheader(‘Host’, SERVER_ADDR)
    requestor.putheader(‘Content-Type’, ‘text/plain; charset=”iso-8859-1″‘)
    requestor.putheader(‘Content-Length’, str(blen))
    requestor.putheader(‘SOAPAction’, “”)
    (status_code, message, reply_headers) = requestor.getreply()
    reply_body = requestor.getfile().read()
    print status_code
    print message
    print reply_body
if __name__ == “__main__”:
    fname = sys.argv[1]
    docdef = sys.argv[2]
    uri = sys.argv[3]
    entry = open(fname, ‘r’).read()
    AddSoftwareFromFile(entry, docdef, uri)

A sample session running this program is shown in Listing 4b.

As you can see, the server merely echoes back the document added to the repository.

But what if we simply want to pass the server a few bits of relevant information for us and have it construct the software repository entry, as we did in the above HTTP POST example? 4Suite Server allows you to write your own specialized SOAP handler as shown in the example in Listing 5. This example handles SOAP messages consisting of the various fields describing the software, composes the description file on the server side, and then, adds it to the repository.

The most important part of this module is theSoftRepoSoapHandler class that is subclassed from the 4Suite Server SoapHandler. All the customized class has to do is define a mapping,NS_TO_HANDLER_MAPPING, which for each namespace defines another mapping from SOAP body element name to a handler function. In our case, we set up theAddEntry function to handle our intended requests.

In order to use this handler module, we must register it with 4Suite Server. This can be done by copying the Python file to a spot on the PYTHONPATH and appending a stanza such as the following to the configuration file.See listing 6a.

Listing 6a

<rdf:Description ID=’SoftRepoSoapHandler’>
    <rdf:type resource=’’/>    

You also need to add a line to the PythonServer or ApacheServer configuration stanza referring to the new handler we set up:

Listing 6b

  <Handler resource=’#SoftRepoSoapHandler’/>

Once the handler is set up, you can make even simpler SOAP calls to add an entry to the software repository. Listing 7 is example client code for the purpose.

Listing 7: An example client to the software repository

import sys, httplib
#define the function
def AddEntry(title, version):
    creator = raw_input("Creator: ")
    home = raw_input("Home: ")
    desc = raw_input("Description: ")
    body = BODY_TEMPLATE%(title, creator, home, version, desc)
    blen = len(body)
    requestor = httplib.HTTP(SERVER_ADDR, SERVER_PORT)
    requestor.putrequest('POST', '/softrepo/soap-handler')
    requestor.putheader('Host', SERVER_ADDR)
    requestor.putheader('Content-Type', 'text/plain; charset="iso-8859-1"')
    requestor.putheader('Content-Length', str(blen))
    requestor.putheader('SOAPAction', "")
    (status_code, message, reply_headers) = requestor.getreply()
    reply_body = requestor.getfile().read()
    print status_code
    print message
    print reply_body
if __name__ == "__main__":
    title = sys.argv[1]
    version = sys.argv[2]
    AddEntry(title, version)

Save Listing 7 and try it out as shown in Listing 7b.

{mospagebreak title=Moving Right Along&toc=1} SOAP support allows integration of our software repository with the rapidly emerging Web services infrastructure, while basic HTTP POST support allows humans and more traditional HTTP-based automation. As we have shown it is fairly simple to build both those interfaces into the same application using Python based services. In the next installment we shall round out the techniques for development of our software repository as a Web Service.


Google+ Comments

Google+ Comments