In our efforts to convert our XHTML representations over to XML and JSON formats, many questions have arisen along the way. Here are some of the issues we’ve wrestled with recently.

XML Namespaces

To make XML representations easier to parse, we decided to use the same namespace across an entire web service. For example, Person Web Service (identity) will have a uniform namespace across all of its resources:

 xmlns="http://webservices.washington.edu/identity"

We originally planned on a unique namespace for each resource type, but a single namespace makes XML parsing – and generation – much simpler. Note that the namespace doesn’t include the version number. The reason for this decision is one of simplicity – a client shouldn’t need to change their namespace when they want to consume a new version of the service, and the client already knows what version of a resource they are viewing because they have requested it in the URI. There was also a little uncertainty over whether we were creating a namespace ambiguity in our use of <SearchResults> as the top level element for all of our search resources. As in the case of version number, the client developer already understands the type of resource they are searching for by specifying it in their URI, so they can also know that within <SearchResults> is a list of the thing being searched for.

Search Parameters

One of the benefits of the XHTML representation was that it made it easy to determine all of a search resource’s search parameters. Each parameter appeared as an <input> element in the search form, and along with it some possible values. From that a query string could quickly be derived. In the XML/JSON representation, all of the search fields are still listed, but not in such a way that they can be turned into a query string. The only guide as to what a search resource expects as parameters is contained in a URI, without much context or indication of possible values. For example, the current snapshot of PWS offers the following URI for its person search representation:

/identity/v1/person.xml?uwregid=&uwnetid=&employee_id=&student_number=&student_system_key=
&development_id=&registered_surname=&registered_first_middle_name=&edupersonaffiliation_student=
&edupersonaffiliation_staff=&edupersonaffiliation_faculty=&edupersonaffiliation_employee=
&edupersonaffiliation_member=&edupersonaffiliation_alum=&edupersonaffiliation_affiliate=
&page_size=10&page_start=1

It’s not exactly something we can expect a client developer to make sense of, especially since a URI is something that is designed to be opaque. This is something that can and should be overcome by sufficient documentation. For the search resource that provides the URI above, I would expect to see in its documentation a list of all of the possible parameters along with what the expected values to those parameters are.