Monthly Archives: March 2009

Breaking News – Id Card Service Beta Launched!

Id Card Service Beta Launched

We launched a new service last week. The Id Card Service exposes data associated with the Husky Id Card, the card that students, faculty, and staff alike use for identification.

Even more exciting, the Student Team launched a web application to consume the service. The application grabs a piece of the data exposed by the service (the id card photo) and mashes it up with data from another source (the student class list from uwsdb). The result is something that instructors have been clamoring for for years – Photo Class Lists. Now instructors can log on to MyUW, click a link in the My Class Resources portlet, and see their class list – with photos!

The Biology department is one of several that have been photographing students each quarter in order to produce their own photo class lists. Biology Professor Mary Pat Wenderoth tells us that the photos make a big difference in her ability to connect with students. When the instructor learns the students’ names, the atmosphere in a big lecture is much more conducive to learning, she says. And having the photo available obviously makes the task of learning names much easier.

About the Service

This is the first service to be built with the web services framework that we extracted from all the great work that went into building the Student Web Service (SWS). The framework is a work in progress but it has already paid off. The IdCard Service was built in a tiny fraction of the time that it took to build SWS and that is partly a result of the fact that most of the hard stuff was already done by the framework. Of course, it is also due to the fact that the id card data is a lot simpler than the student data, but still…

We only started working on the service in mid-February, squeezing it in between other projects. Getting it (and a consuming app) launched in time for Spring quarter is pretty sweet. Things don’t usually move that fast around here 🙂 It makes me excited about our prospects for moving quickly on building out a whole series of RESTful data services in the future.

We also broke a little new ground with this service. The photos don’t change very often so we had a chance to experiment with caching. We set up a caching layer that allows us to check authorizations and log access but avoid the rest of the processing. We learned how to serve binary data from a Windows Communication Foundation (WCF) service and wrote code to produce and save thumbnails of various sizes too.

Next Steps

Our main issue is to identify data stewards who can authorize applications to use the id card data. The registrar’s office authorized access to student photos for the purpose of photo class lists but that still leaves questions around what other uses will be allowed and who will authorize use of faculty and staff photos.

We will also be working with developers to gather requirements for exposing more of the id card data in the service, for exposing photos of various sizes, and to determine what sort of performance will be necessary to serve many clients.

Hopefully soon we can look forward to UW developers mashing up this data with other information to solve all sorts of current business problems.

Onward and upward!

Webservices Registry version 0.5

We’ve updated the UW’s registry of webservices to version 0.5. It is a static HTML page that is marked up so that it’s readable by human and machine. It roughly follows our spec for version 1.0 of the registry, but the main thing is that you can go there to see what services are available and get pointers to documentation.

See it here:

What is ROA (Resource Oriented Architecture)?


Since this blog launched last week I received a couple questions asking us “What is ROA?”. Since this blog is named “On the ROA” it seemed necessary to answer that question!

So what is ROA?

“Resources Oriented Architecture is a way of turning a problem into a Restful web service: an arrangement of URIs, HTTP, and XML that works like the rest of the Web, and that programmers will enjoy using.” – Restful Web Services (Leonard Richardson, Sam Ruby)

Our answer is that Resources Oriented Architecture (ROA) is an overall system design that embraces RESTful design philosophy. It has a lot of overlap with Services Oriented Architecture (decentralization and small interoperating services) but it means that instead of treating our functionality and data as service calls; we treat them as resources in the RESTful sense.

In the early days of grappling with web services here at the UW many of us working in various IT departments investigated SOA (Service Oriented Architecture). During this investigation we were introduced to Pete Lacey, who introduced us to Restful web services. This led to a SOA workshop which many developers and technologists on campus attended. The idea of building Restful web services vs building SOAP web services on campus seemed to take hold probably because of the heterogeneous nature of computing here at the UW. The need to be technology agnostic in our approach to deliver data and automate processes seems to make a lot of sense in order to ensure all parts of the UW can take part in leveraging information services. In addition, the REST (Representational State Transfer) approach to constructing web services allows a very simple interface between systems (services and clients), and it scales well.

Following the Restful path, we soon discovered that there was a term that was being used to describe an architecture based on Restful design practices: Resource Oriented Architecture.

With that said, the bottom line is that the UW has a lot of information that people and applications need to access in order to keep the UW well positioned for the future. That information needs to have a low barrier for access and at the same time be safely accessible. We believe that planning our data access needs for the future using ROA and building web services based on a Restful design is one way that can help us meet this need.

Slides from Webservices Discussion Group

Here are the slides from today’s talk on the Allen Center kiosks.

The PHP in these slides should be good, but keep in mind that I edited it by about 30% so it would fit on one slide. I’ll be glad to share source code for any of this with anyone who might need it. PHP programmers who are about to consume their first webservice might get a boost from looking at it. If you have any question, please don’t hesitate to ask.

And thanks to everybody who came today!

Error Documents for RESTful Services

Where you have software, you have errors. Web services are no exception. When talking about the design of RESTful web services, a problem quickly rears its head:

HTTP Status Codes are Pretty Inflexible

Since we’re following RESTful principles here, we already have a tool to communicate these errors: the HTTP status code. Now – this is a pretty good system as far as the transport protocol goes, and the formally defined codes available cover lots of the generic cases such as “I just don’t know what you’re asking for” and “I can’t let you see that.”

But I’m pretty sure you see the problem. My service for letting instructors grade a student’s homework may choke on a request that tries to set the grade to ‘4.2’ and there’s no HTTP status code for “Grades don’t go that high.” Some people have tried to extend or build on top of HTTP to cover some important domains but you can’t cover everything (or get everyone to use your extension).

Luckily, HTTP accounts for this with some general status codes such as “400 – The request could not be understood.” HTTP recommends that you provide not only a status code of 400 but a document body that describes the error. When a client sees a 400, it can dive into that payload to get more information.

Similarities Emerge

The ROA Technology group recently looked at the error documents that a variety of services produce, and found that the approaches were quite similar. Based on examples from the Student Web Service, Catalyst, and Amazon’s Web Services offerings, we would like to offer the following recommendation.


The format should be easily parseable. We recommend XHTML because of the huge number of tools that know how to parse and display it, but many other formats would do just as well.

Three distinct elements for three distinct audiences. Three types of viewers will probably see your error messages: HTTP clients that are actually doing the transport, programmatic client code that understand the content or purpose of the service, and humans who are programming to, debuging, or using your service. So:

  • error_http_code Include the numeric HTTP status code used to report this error. Anything that knows how to react to generic HTTP codes will thank you.
  • error_key A short, unique string that identifies the error. This should be used to allow client code to programmatically react to errors in at a more granular level than the HTTP status code. These should remain as static as possible to avoid breaking code!
  • error_description A human-readable chunk of text or hypertext intended to help a user of the service identify and resolve the error.

These documents could be extended with new elements. Your service might have good reason to include other useful bits of information, and we encourage this as appropriate.

An Example!

Recommendations without examples are no good, so:

<html xmlns="" xml:lang="en">
    <div class="error_http_status">400</div>
    <div class="error_key">InvalidHomeworkScore</div>
    <div class="error_description">
      The score you included in your request was not within the acceptable range
      of 0 - 100 points.
      Please refer to the
      <a rel="documentation" href="">scoring documentation</a>.

Great! Now, my HTTP library can avoid caching this since it’s an error, my client code can notice “InvalidHomeworkScore” and tell my end user that they need to try again, and when I was programming my client, it was easy for me to figure out what the heck was going wrong.

A serendipitous world

If you are interested in whats happening in the land of web services at the UW – this is the place to be. At this blog you will be able to keep up to date on the latest events and news related to web services on campus. This includes learning about up and coming delivery of web services, projects and applications that are using web services, and various technical post on the development of web services. Whether you are a business professional, technical geek, or everything in between we hope this blog will be of lasting value to you. With your blog participation we can all realize the serendipitous potential of web services for years to come.