Monthly Archives: September 2010

Adding XML & JSON Reps: Sprint Update II


XHTML deprecation

While working thru the technical details of offering both our default XHTML and upcoming new JSON and XML representations; the team began to more fully understand the long-term costs of supporting all three different representation formats.
As a team we have decided today to decrement xhtml in future releases only after we have spoken to more clients to understand timing. In the short term we will offer and support all three representation formats.

Why decrement XHTML?

  • All our client research (uservoice and developer interviews) has pointed to the fact that developers would rather program against XML or JSON than XHTML.
  • XML and JSON are the most common formats on the internet and we would like to stick with that trend and help our developers take advantage of frameworks that can easily parse one or the other.
  • The long term costs of supporting XHTML in our code seemed to outweigh the benefits for our clients.

Although many of us like the human readability of XHTML in a browser; we felt the feature did not warrant the costs of continued support. In addition, we felt that those who have already coded against XHTML would have marginal difficulty consuming our XML representations. We plan on giving the UW plenty of time to move over to the new representations.

We plan on starting our community outreach immediately so we can talk to folks on when we can effectively decrement XHTML. A method of transition will be for us to start discouraging the use of XHTML by new clients – especially in documentation by making the xhtml format content less prominent on the page and highlighting the fact it will be unsupported in the future.

ATOM pub research

While investigating what common XML representation we wanted for all our services we briefly researched the use of ATOM. Google’s Gdata and Microsoft’s OData is based on Atom pub for generic data delivery so wanted to see how they were using it. We also liked ATOM’s default rendering in all major browsers; making our web services human readable in a browser. Something we liked about our XHTML payload but like I mentioned above planned on decrementing.

After looking through the SyndicationFeed class in C# we felt that it did not offer the flexibility we needed. We wanted to get ATOM pub for “free” meaning that we can just simply serialize our model objects into ATOM using native .NET framework classes. Again the extra work and support or costs to make ATOM happen didn’t justify its use.

As Scott already mentioned in the last blog post we will use a very simple no attribute (all elements) XML representation.

Visual Studio 2010 Conversion

Today we successfully upgraded our UW.Web.Services Core framework to VS 2010 and .NET 4.0 using EntLib 5.0. This was a successful milestone. Shortly after we successfully retrofitted Person Web Service with the new core and complied the service against .NET 4.0 with no problems.

We are getting there and now we need to convert our other services and begin creating our new view models to support JSON and XML.

Adding XML & JSON Reps: Sprint Update

We began a two week sprint began on 9/14/2010 with the primary goal of adding XML & JSON representations to all resources in all the existing services to complement the XHTML offering. The addition of XML is the #1 requested feature on UserVoice  and follow-up polling indicated that JSON was similarly desired and can be done without too much additional effort. Other technology renewal work will be done concurrently, including upgrading to .NET 4.0, Visual Studio 2010 IDE and Enterprise Library 5.0.

9/14: Discussed the possible tasks, prioritized each, decided which will actually be done/attempted, and assigned pairs to work on each task. Work began in earnest.

9/15: Accomplished/decided the following:

  • Gathered baseline performance numbers for several of the services. We will compare the new versions against this baseline to be sure we haven’t introduced performance problems during our work.
  • Technical deep dive compared the XMLSerializer with the DataContractSerializer to decide which one we will use to automatically generate the XML representation. We decided to stick with the DataContractSerializer for a number of compelling reasons, even though it means we won’t use element attributes, just elements.
  • Alpha versions of the Financial Web Service Budget and Budget Search resources delivering XML and JSON are working.
  • .NET 4.0 and Enterprise Library 5 upgrades are proceeding nicely.

We chose the DataContractSerializer(DCS) over the XMLSerializer(XS) for these primary reasons:

  • Microsoft guidance, and beyond, recommends the DCS over the XS. It’s about 10% faster, for starters.
  • DCS supports both JSON and XML serialization and the XS does only XML; using one serializer means much less possibility for introducing unforseen bugs.
  • DCS is an ‘opt-in’ serializer, meaning that properties that are to be included in the serialized XML must be decorated with an attribute. XS is ‘opt-out’, serializing anything that is public. Opt-in is a better model for us since we are dealing with explicit contracts.
  • XS requires a public setter on each property to be serialized. In read-only services (the majority) we don’t want this, and having it could introduce bugs.

The effort is progressing nicely and so far we are optimistic we can complete it in the two week window.