One developer’s perspective on the SWS’s course search resource


The Office of the University Registrar (OUR) recently posted an entry on its blog about an improvement to the course catalog search, aptly titled “Course catalog search, at your (web) service.” That entry discusses the improvements in the catalog search in terms of features and usefulness to students. It mentions the UW’s Student Web Services (SWS), but doesn’t go into detail, as that blog’s audience likely isn’t interested.

You, dear On the ROA reader, are. Let’s dive in.

Background

First, a little background: The OUR has wanted a better, data-driven interface to the course catalog (CC) for years. Though the usefulness of moving away from dozens upon dozens of static HTML files was clear, the complexity of establishing such a system—not to mention the time and cost—stymied attempts to set something up. Enter the then-unnamed UW iPhone app. Given that it needed to consume course data from somewhere and the app had support from the President, the “course search” resource was implemented in SWS v4. That Herculean effort by the Office of Information Management (OIM), UW Tech, and the OUR cannot be understated. Thank you everyone!

Getting data from the SWS

The course resource itself presents a simple search form. Interacting with it as a human is a simple (albeit plain) task: enter a search term(s) and constraints, hit search, and revel in the resulting list of matching courses. Neat. But how can a system interact with it?

Answering that question fully is beyond the scope of this article (besides, there are already good resources available on that topic). However, I can outline how the CC search works:

  • I’m a PHP developer, so I chose PHP’s cURL library to consume data from the SWS. (Thanks to Paul Hanisko in the College of Education for sharing his web service code with me early on.)
  • SimpleXML is an extension to PHP that allows for easy manipulation of XML data as a PHP object.
  • With these tools set up, I was able to write a PHP class, Http_SwsCourse, that extended cURL’s HTTP class. I fed the class the base URL for the public course resource and wrote some helper functions (such as getting the count of the returned results) and I was all set to build the interface.
  • The interface is explained in more detail below, but at its heart is just an HTML form. When submitted (via GET), the interface creates a new instance of the Http_SwsCourse class and sends the sanitized user input to the SWS. In essence, the class builds a query string just like the one visible in the browser’s address bar when using the course resource directly.
  • The resulting XML payload from the webservice is then manipulated—using SimpleXML functions—by the class’s functions. Really, only two are of consequence. One retrieves all matching courses, the other “dives deeper” and retrieves course details using the specific course syntax: /course/year,qtr,curriculm,course-number

Building the search interface

Though it’s not directly related to the course resource or the SWS itself, a brief discussion of the creation of the interface for the CC search is warranted. The overall goal for the improved search was simplicity.

  • Streamlined inputs – A single text-input box for the user’s query dominates the page; advanced options are hidden away. Even the advanced options are presented in a streamlined fashion. For example, I added a “search from start” checkbox rather than a second input field, and the year input is a drop-down menu listing only the current and upcoming years.
  • Validation and sanitationjQuery enforces some sophisticated field validation to match the SWS’s needs. For instance, a search term is required unless a curriculum is entered; and a year is required if a quarter is selected (and vice-versa). All variables are “sanitized” (whitespace trimmed, slashes and other undesirable characters converted, etc.) before being submitted. This is already done by the SWS but it never hurts to ensure user input won’t do any harm!
  • Ajax – Mirroring the course resource’s structure, the resulting list of matching courses offer links to a given course’s details.  Rather than send the user to another page to view those details, I implemented an ajax call (again using jQuery) to retrieve and display that information. After years of static HTML pages, I thought the UW’s students and faculty deserved a little eye-candy along with their information.
  • Feedback – The free version of a user-feedback service, Kampyle, provided an opportunity for users to point out any issues or offer suggestions. It’s a wise idea with any application or website, but especially so when it’s new and admittedly a beta.
  • Accessibility – As noted in the beta disclaimer, the beta CC search is does not yet fully meet accessibility standards. It can—and will—when it is ready to replace the primary (Google-based) CC search. It should be relatively easy to do so, as the markup is clean and all ajax content is accessible with regular anchors and URLs.

Thoughts on the SWS course resource

Given the time constraints the OIM was under it’s amazing there aren’t dozens of problems with the web service. In my experience with it, there are none. The minor discrepancies noted by users of the CC search were related to the data or the interface I created, not the webservice. I experienced no issues with the production version and found my first foray into programming that consumes from a webservice very smooth. Again, congratulations are due to those who made this possible.

That said, there are features that I—and many, many users—would like to see in the course resource:

  1. Description search – The most requested feature. Currently it only searches long- and short titles.
  2. Attribute search – Searching by various course attributes was the runner-up in terms of volume of requests. For example, “show me courses that satisfy I&S or NW” or “I only want to see 3-credit courses.”
  3. Sorting and paging – In building the search interface, I found that sorting options other than the default were not available. I was able to pseudo-sort results once they were in an array. This method, however, is dependent on the page-size variable in the SWS. I’d like to see more robust sort options: by number of credits; alphabetically by course or curriculum code; by course number; etc.
    As a workaround, the option to retrieve all results in one request would allow proper sorting and alternatives to paging (like an “endless scroll“). It might, however, be a heavy burden on the webservice, as some searches return many hundreds of results.
  4. Instructor Course Descriptions – If these could be linked to or otherwise added to the course resource, the webservice would be sufficient to replace the static HTML version of the course catalog.

Conclusion

The beta CC search is really just the tip of the iceberg. Webservices are “game changers,” and I’m happy to have had the opportunity to build one of the early tools on campus that consumes them. The process was easy, flexible, and can only get better from here. Again, I’d like to thank the OIM, UW Tech, and the OUR for making the SWS a reality on this campus.

And I’d like to thank Tony Chang for inviting me to write a guest entry for the On the ROA blog. I enjoyed writing it; I hope you enjoyed reading it.

PS – If anyone would like to see the PHP code I wrote, let me know. I’m happy to share.

,

Comments are closed.