Author Archives: Rupert Berk

SWS 2014 Release Plan

We wanted to give you a heads-up on some changes coming for SWS in 2014.

We are currently developing an exciting new Web API infrastructure based on Elasticsearch to deliver fast and low-latency student data. When we release this new infrastructure, targeted for late December, you will see fast, fresh responses from the section, registration, enrollment, and course resources.

In the meantime, there are various API changes we need to make in order to help get us there. These changes, summarized below, will reduce code debt and allow us to release faster.

June 3

v5.0 in evaluation environment, ready for testing. Documentation made available.

June 24

  • v5.0 released
    • New data: notices, enrollment minors, person finance
    • Xhtml contracts will change; Xhtml is no longer supported as an API in v5 (except grade roster), but will be available for browser use; applications encouraged to migrate to v5 JSON, though XML is supported.
    • No more ‘public’ resources; all access requires some kind of access token e.g. X509 certificate. We have decided to require an access token for all users so that we can better track usage and better communicate service changes.
    • A handful of other minor contract breaking changes. Mostly, we are making some of the data types more consistent across resources.
  • v4 deprecated, to be retired in December.
  • v3 retired (there are no longer any users)

Late December (Target)

  • v5 “ES” released
    • No API contract breaking changes
    • Elasticsearch search index integration for fast query for section, course, enrollment, and registration resources
    • EOS non-credit course data integration
  • v4 retired

As always, please contact us if you have questions, concerns, or ideas.

New SWS Service Level Agreement

We have published an SWS SLA.  A couple of important differences from the previous service policy documentation:

  • We will provide at least a six month notice before we retire any interface. Interfaces (v3, v4, etc) pass through different life cycle stages: in evaluation, released, deprecated, retired
  • We have also published our cache policy.

Take a look at the Service Level Agreement (SLA).

Space Web Service 1.0 has been released

The product of a joint project between UWIT and OPB, this new REST Space Web Service provides near real-time, authoritative data about University facilities and rooms. The data are currently sourced from the Space Inventory Management System (SIMS) and the standard UW Business Web Service formats are available (XML, JSON, XHTML).

Please see the online documentation for information about the API, support policy, and how to get access.

Think about the mashable possibilities with facility center point, room capacity, room square feet, and more!

UW Web Login support available for Business Web Services

You can now be authorized to use your UW NetID and password to login to UW Business Web Services that have enabled this feature. So far, the only service to offer this feature is the Student Web Service (also requires Entrust Token for two-factor security), but it can be enabled for the other services such as PWS, FWS, or HRP if there is interest. This Web Login support will be enabled for the forthcoming SpaceWS service.

Web Login support is particularly helpful for developers who want to browse the service without an X509 certificate installed in their browser. X509 certificates are still required for programmatic access.

How to request content types (XML, XHTML, JSON, etc.) from RESTful services?

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:

  1. URI query string

    GET /books/12345?format=xhtml HTTP/1.1
     
  2. URI file name extension

    GET /books/12345.xhtml HTTP/1.1
     
  3. Content negotiation using the Accept header

    GET /books/12345 HTTP/1.1
    Accept: application/xhtml+xml
     

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.

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?