Archive for January, 2011
Web services that output Xml and Json as well as Xhtml?
You asked for it, now you’ve got it!
The Student Web Service released to production yesterday and the Financial Web Service went out this morning.
A big thanks to everyone who tested in eval. We can’t wait to see the cool things you build with this!
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.
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:
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.
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=®istered_surname=®istered_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.
A build of Student Web Service with XML/JSON/XHTML payloads for all resources (with the exception of GradeRoster) is ready for testing. This is in response to many of you who shared with us your thoughts via Uservoice, emails, chat, and/or face to face meetings. We understand that to help advance developer adoption of web services it is important we offer XML and JSON representations of our web services.
Things you should know:
- Production release scheduled for the end of this month.
- All uris, including public, have remained unchanged for Xhtml. Please see below for examples on how to get XML and JSON representations.
- Although we have a good build ready for testing there are still some bugs and design considerations we will likely fix before we release to production.
- If you already have access to the web service then no new authorizations are required from the Office of the Registrar.
- We plan on decrementing Xhtml some time in the future and will provide ample communication prior to that change.
SWS EVAL Test Environment examples:
1. Using Course Search to find all Math courses using JSON or XML. Append .json or .xml to the end of the search resource name.
2. Get public course information for Math 100. Append .json or .xml to end of the uri.
Developer documentation for these new formats is available here. The target date is about 2 weeks from now so please help us find bugs before ship date.
Your timely feedback and bug notifications will be greatly appreciated to us and the rest of the UW. Please send all issues and bugs to firstname.lastname@example.org.