Archive for November, 2009
In a recent ROA Technical team meeting we discussed as a team what things should and should NOT go into the Registry. The intention is to expand the scope of the Registry to list all useful programmatic web end points including RSS & ATOM feeds vs just focusing on web services designed and built by UW developers. The goal for the Registry is to be the first stop for developers needing programmatic access to UW data over the web. Let us know if you think there are other things we should add or remove from the list.
What should go into the Registry?
- Something that is accessible over the web (in other words uses http)
- Contains UW data
- The content is machine parseable (json,xml,xhtml)
What should NOT go into the Registry?
- Oren’s Blog (RSS/Atom feed)
- A link to an HTML page that is NOT XHTML strict
How should web services determine the format of a response to a client? Or how does a client ask for XML, XHTML, or JSON?
This question is becoming more pressing as UW web services such as the Student Service, Financial Service, and ID Card Service begin to expand their format offerings. These services began with just XHTML, largely due to how conveniently it renders in a browser, but a growing number of developers have vocalized their desire for a more terse XML format that works with their libraries and tooling that read XML, but not XHTML.
In our recent discussion of this issue on the ROA Technical team, we considered several options for how to request content type:
- URI query string
GET /books/12345?format=xhtml HTTP/1.1
- URI file name extension
GET /books/12345.xhtml HTTP/1.1
- Content negotiation using the Accept header
GET /books/12345 HTTP/1.1
There is plenty of debate about which is the better approach.
In their book, Richardson and Ruby prefer the explicit URI specification over the content negotiation:
Unlike humans, computer programs are very bad at dealing with representations they didn’t expect. I think an automated web client should be as explicit as possible about the representation it wants. This almost always means specifying a representation in the URL (RESTful Web Services, 94).
We lean that way, too, and prefer the URI file name extension option. It’s intuitive from all of our Web browser years; it’s simple; and it’s easy to test in a browser (you don’t have to monkey with headers).
We also think services should expose a default extension-less URI that either redirects to the .xhtml/.xml resource or returns a location header to it.
GET /books/12345 HTTP/1.1
Even though we think that the URI file name extension option is preferable, we’re not too religious about it. As long as the contract is made clear, any of these three methods are acceptable.
Let us know what you think.
The following entry was published on the Office of the University Registrar’s blog earlier this week. It’s relevant to On the ROA readers, so it’s reposted here for convenience.
The term “web services” has been used frequently on this blog when discussing new tools for the University community. Some examples include m.UW, the UW’s iPhone app; an improved course catalog search; and Kuali, the next-generation student software initiative. With the fourth version of the Student Web Services (SWS) open and available for use, it’s time that the Office of the University Registrar officially invite interested developers (and their managers!) to dive and start creating new, useful tools.
Okay, but how do I start?
That’s a good question. Here are the ingredients necessary to get a SWS project off the ground:
- Join the community – The UW’s web services community is strong, and if you’re going to develop something using SWS you should get to know it. Read On the ROA, the UW’s web services blog; review ideas from other developers at UserVoice; and stop by at a Web Services Discussion Group meeting. Sign up on the “appdev@u” mailing list to be notified of meeting dates and locations.
- Identify a need – Have you wished there was a site that did X? Are your students asking for Y? Want to find a better way to display Z? Once you’ve identified something to build, fix, or improve upon, you can plan a web site, iPhone application—or something else—to accomplish it using the data available to you (see number 3).
- Research the services at your disposal – The Web Services Registry is a maintained list of UW web services, including a description and links to documentation and a contact person. You can also submit your own UW-centric web service to the registry. But don’t limit your idea to UW-specific data; maybe there’s another dataset that you could mash up it up with?
- Build it – Web services really shine when it comes to accessing data. If you’re using public information you can simply access the service you want and start using the data returned. And it’s easy to do so regardless of your preferred language: PHP, Python, .NET, Ruby on Rails, etc. There’s a PHP class already available to simplify things even further; a .NET version is in the works.
What about an example?
Part of the reason for inviting the community to built tools with SWS is the “serendipity” factor. With pubicly-available data and a whole community of smart people, the sky’s the limit on what sort of useful tools might emerge.
An example is the recent improvements to the University’s course catalog search. A developer in the Office of the University Registrar saw the data available, knew of the issues with the current Google-based search, and built a prototype replacement in just a few days. A presentation of this tool’s development was recently given at the Office of Information Management’s Community Forum (the developer’s slides are available for download).
So go ahead: wow your students and the University as a whole with your creation. Show us the tool we didn’t know we couldn’t live without.