Write a Better Web Service

No two companies are identical. Their business needs are often very different. Something that works for one company might not work for another. A “one size fits all” approach can easily lead to a bloated web service where 90% of the users will only use 10% of the functionality.

Recently I worked on a project at work where I had to integrate our timeclock management software with a Workforce Management Application. Even though a large and very well respected company wrote these web services, I found them to be an example of what NOT to do. Once web services are published they can become very difficult to change. Whether you’re utilizing REST with JSON, or SOAP with XML, or something else entirely, it’s extremely important that your web services be well thought out. You want to be verbose enough to be clear but not so verbose as to be cumbersome. The web service written by this particular company fell into the latter category. Let’s take a look at two versions of the same web service call (the names have been changed to protect the guilty, and details have been omitted for brevity).

Fig 1. TimeClockEvent Object

The TimeClockEvent object actually has 15 different fields for Custom Organizations and another 15 fields for Custom Tags. While this probably made the server-side code simpler for their developers to write, it makes the WSDL horribly bloated and rigid. If a customer requests a new field to support some new functionality, for example, let’s say they want to include a work order number on the event and they’ve used all their Custom Tags? The WSDL will have to be modified, made available to all customers, code changes will be required to support the new field, regression testing, etc. While this may not sound likely or like a big deal, it’s clear this is not exactly an elegant or extensible solution.

Let’s take another approach to the same web service, this time with the goal of keeping the service as simple and lightweight as possible while still being as powerful as possible.

Fig 2. Restructured Web Service

I promise you this version of the web service is capable of everything the first version was (and more!). The difference is that this web service puts the burden of type and range checking on the server-side code. But really, the server should be doing that anyways.

At this point you may be saying, “Okay sure the second way is simpler, but why should I care?” I’ll give you an example why. Our time clocks have the capability to send custom tags to our integration middleware making their functionality very flexible. However, to handle mapping these custom tags to the appropriate fields in the Workforce Management application, we have to have a switch/case statement for each of the possibilities. That’s a long, difficult to read, and annoying to maintain switch/case. A popular topic within the realm of SaaS is “configuration not customization.” In the same vein, if the web service were written like the second version, then that whole switch/case statement could be removed and the custom tags and values could be put straight into the request, something we can do by configuration instead of code. Additionally, the only testing that needs to be done by customers is system integration testing.

Let’s take a look at a use case for these custom tags; Mary runs a facilities management company. Rather than using time clocks at fixed locations all of her workers carry smartphones with an app. The app captures the GPS coordinates and attaches them to each punch. Mary also wants to capture information about the work performed so it can be passed off seamlessly from one employee to another when necessary. Dan has been sent to Melvin Hall to investigate a problem with the heater. He punches in once he arrives on site. Once he figures out the problem he makes a note using the same app. The app sends a “DATA” punch with that information. The Workforce Management/Enterprise Resource Planning (WFM/ERP) system knows that DATA type punches are informational only and do not affect payroll. Because Dan tagged his coworker Jim in the notes, the WFM/ERP system will send Jim a notification so he can order the necessary part. Finally, Dan punches out as he leaves the site.

Fig 3. New Features with Improved Web Service

With the first version of the web service, where do we put that information? Well I guess we put it in the “Custom Tag” fields, and use the projectId field for the work order number. We will ignore for the moment that this particular service doesn’t actually have the concept of a “DATA” punch.

Fig 4. New Features with Original Web Service

While I realize this may be more pleasing to the eye and more human readable, the reality is the only human that will be reading it will be the original developer. The real issue here is how much we had to mold and shoehorn our business processes to fit into the form this service expects. Let’s imagine if we want this data to feed into our procurement process. We define a custom report to list all of the part numbers we need to order. What field is that in again? Is it customTag3? No that’s the status, I guess it’s customTag4. Instead of mapping this data once at the source (Dan’s smartphone) we now have to map it into some intermediate form and then map it back. What’s worse is that every customer who uses this service will have to do the same thing unless their business processes magically align with what’s defined here. Additionally, if we needed more than 15 custom tags we’re out of luck.

When writing a web service one should try to leave room for flexibility. Assuming you know exactly what your customers need can lead to rigid, bloated services that don’t fully accommodate those needs. The alternative service I presented here takes flexibility to the extreme, and the reality is that the best service lies somewhere in the middle. Apply bounds and types on as much as makes sense but no more. Make sure to leave room to accommodate unforeseen requirements.