Archive for May, 2009

What constitutes a version change?

Recently, in the ROA technical group, we discussed what constitutes a version change in our RESTful services. Many of us have adopted the versioning convention of embedding a version integer in the URI as supported in the Richardson and Ruby book

/student/v3/course

So when do we need to change this integer? As we add new data elements to our fledgling services, we are concerned about a proliferation of versions, and in particular, URI’s. Do we need to change URI’s with the addition of each new element? To do this too often seems to add unnecessary complexity and maintenance cost. Instead we have decided that minor changes that are “additive” do not necessitate an integer version change and consequently do not require a change to the URI.

By “additive” changes, we mean changes that wouldn’t break xpath queries based upon the class attribute:

/html/body/div/span[@class='foo']

as opposed to a queries based upon the ordinal relationship of elements

/html/body/div[2]/span[3]

(We consider the use of queries based on the class attribute a better development practice.)

One concern is that even if we don’t break clients with a version change, how do we communicate the change. We are recommending the inclusion of a programmatically parsable xhmtl version element in the root of each service that describes a fuller version, perhaps with major, minor, revision, and build.


<div>Service Code version:
<span class="service_code_version">3.0.1.26481</span></div>

That should allow for programmatic detection of version changes. And, of course, we still advocate application support email lists to communicate any change in service contract.

What do others think?

2 Comments

Student Web Services V3 Release

SWS V3 is now available on our production web server and we plan on deprecating V2 within the next couple of weeks. Since Catalyst is our only client using our V2 production web service we are expecting little to no impact to anyone else.

SWS client docs are available here. Below is a quick summary of V3:

SWS V3 Public Resources
We now have public APIs which require no client authentication. The resources have been designed with the Office of the Registrar to ensure that the data is safe for public consumption. The following public resources are available:

• Course
• Course Search
• Section
• Section Search
• Term

The public resource can be accessed like in these examples below.

Section: https://ws.admin.washington.edu/student/v3/public/course/2009,summer,info,344/A

Section Search: https://ws.admin.washington.edu/student/v3/public/section?year=2009&quarter=summer&curriculum_abbreviation=info&course_number=344_id=

NOTE: Due to network configurations, http://ws.admin.washington.edu, is currently unavailable outside the UW network. This is currently being addressed and we plan on having our end point available outside of the UW network shortly after 6/15.

SWS V3 Updated Resources
The resources below have been updated including a new attribute to the section resource called the Class Website Url.

• Course
• Section
• Registration

Please continue to log and vote for feature requests on UserVoice. Please subscribe to mailman list (http://mailman1.u.washington.edu/mailman/listinfo/sws-client-app-dev) for future notification of production changes to SWS.

No Comments

Web Service Registry

For anyone with a Web Service, or anyone who wants to consume a Web Service, I have some exciting news. At the end of March, Miles Crawford sent out an email to the Appdev list soliciting help building a registry for such items. I’m happy to announce not only did he get a response, there is actually some tangible code.

The original desire was “…a technical tool to help identify and locate resources, but also as an outreach tool to better connect the groups behind services.”  To anyone who has tried to obtain data from anywhere around campus the need is certainly apparent.  Even though there is a trend to create Web Services and offer data, as before, finding out what data is available and tracking down who has it is a huge problem.

In the spirit of openness and the chance to work with new people and technologies the following team was born:

    Miles Crawford – Learning & Scholarly Technologies
    Tony Chang – Office of Information Management
    Chris Heiland – UW Marketing

We knew we needed a framework, source control, and a server.  The last part was the easiest to decide, Catalyst was kind enough to allow us a temporary home on one of its servers.  Since we had near-complete freedom on the choice of technology we spent a bit of time deciding on the technology needed to implement the service.

I want to stress strongly that our choice in frameworks, languages or source control is not going to be the best choice for every job.  Yes, there are numerous other options and they all have their pros and cons.  The goal for the technology was to support rapid development and a short learning curve, none of us wanted to spend the entire project lost in a manual.

The project was a temporary solution to a current problem, but the solution had to last from several months to longer.  Thus we were not looking for something that would scale to an enterprise deployment (thousands of services, millions of hits, constantly changing data), but if there was the ability to handle the load then we wouldn’t turn it down.

We decided to use Python as our language and Django as our framework.  The framework is fast to deploy and certainly excels at CRUD-style applications.  If this does become the permanent solution then we certainly have the option of leaving the registry as a Django app.  A bit more caching in a few places and no more pilot status.

For source control we did not require an elaborate solution, any system could handle what we needed.  Also, as we saw this as a chance to stretch a bit we decided to look at Distributed Version Control, specifically Git.  Git may not be worthy of all the hype, but there are some very clear advantages versus systems like SVN or CVS.

Again, there is no perfect tool for every job, we could have easily set up Subversion and been done with it.  However this was a chance to learn a new tool.  There was also the opportunity to host our code at GitHub, which had space and fell under the ‘nifty’ factor.

After a few short meetings of discussing what features to include and adding some  more to the Scope Creep Bin, we started coding.  In a short amount of time we had a working application and the ability to quickly manipulate test data using the built-in admin interface.

There is still a bit more work to do before the application is released, but we are very happy with the progress.  Very little code is needed to put together something functional and the framework is very straight forward.  Overall we are excited and preparing for launch.  Until then you know how to reach us.

2 Comments

Cool, RESTful system for course-based access to library resources

Summarized below, this system from NCSU seems like a great RESTfull data mashup.

http://journal.code4lib.org/articles/1218

The NCSU Libraries’ Course Views project, along with a locally developed widget web service, improves course-based access to library collections and services by dynamically generating library course pages for all 6000+ courses at NCSU. By automatically generating custom content when possible and showcasing authored content when available, Course Views is able to achieve full course coverage without significantly increasing staff time to create and manage content.

No Comments