RESTful Web Services and Weed Trimmers

April 5th, 2011 by dsmith

By guest author Donald Smith Jr.

I was standing in the local home improvement store staring at all of the choices available for yard trimmers. Since it is spring, the annual tradition of assessing my lawn equipment needs for the season has me frustrated that it is the year 2011 and the technology available to cut weeds still sucks. My problem is that I have bought many yard trimmers over the years including gas, cordless, and corded trimmers. Each one has advantages and disadvantages.

Why Weed Trimmers Suck

I absolutely despise gas trimmers. I never have gas on hand when I need to cut the grass, or the gas/oil mixture. Yeah, I live close to a gas station and the home improvement store, but I always have to stop what I was doing and make two stops just to cut weeds at the house. Plus, I spend twenty minutes trying to start the damn thing and then spend the rest of the day trying to ignore the vibrating feeling in my hands.

A cordless trimmer suffers a similar problem, the power source. If I remember to recharge the battery, which I never do, someone will most likely have unplugged it to charge one of the riding toys for the kids. The other problem is that it isn’t powerful enough to cut all of the weeds. It gets most, but there is always a few that give me trouble. Oh, the battery also dies on the home stretch.

A corded trimmer is the best in my opinion. I don’t need to remember to buy gas and oil, or remember to charge the battery. The only issue here is the line. You know the fishing line looking stuff that is always breaking and takes hours to get feeding properly. It reminds me of fishing with my kids. Something that could be enjoyable (yes I like yard work) turns into a day of frustration. Just like fishing, I spend more time rigging equipment than actual fishing. There are options available to fix the trimmer line issue. After market trimmer heads are available that offer quick loading with just short pieces of line. Problem is, they only work with gas trimmers. A corded trimmer requires that I purchase a new spool every time it runs out of line. These cost anywhere between five and ten dollars. At this price, I should just pay someone to mow my lawn for me. It feels like the trimmer just eats this stuff.


I left the store frustrated without buying anything. On the way home, I started thinking about the tradeoffs I was facing and thought about a project that I had at work. I am currently building a RESTful web service. Yard trimmers and software seem to have a lot in common. There are many tradeoffs that we have to consider. In software, many decisions such as technology choice, scalability, time to develop, and ease of use by end users are decided by really strange factors. These always seem to be arbitrary and non-sensical to me. Thankfully, unlike yard trimmers we have a better way. Getting there is the problem.

The Web Built a Better Trimmer

There have been many discussions and debates about what makes a REST API RESTful. Most of these discussions break down into squabbles over URL patterns, versioning, and query interfaces. I think most have missed the point of REST. The idea here is that as the user I do not have to worry about the problems associated with using the service. The HTTP uniform interface saves me from having to read a volume of documentation before I can use it. I already know HTTP, just like I already know how to use a yard trimmer. The yard trimmer requires me to plan ahead. I either need gas/oil, a charged battery, or expensive replacement line. Not so with REST. Unlike the trimmer, HTTP is ubiquitous. It works the same no matter where you go on the web.

REST has become a marketing term. It is difficult to find a web service that actually follows the architectural style laid out by Dr. Fielding and the other creators of the world wide web. REST boils down to three important things, respect the HTTP uniform interface, use of resources and identities, and hypertext as the engine of application state. Almost all of the “REST” web services give us the first two, but very few provide the third. Without the third, we are missing the most important part. Hypertext As The Engine Of Application State (HATEOAS) was something I misunderstood from the beginning. I am a developer, so I do what other developers do. I try to equate concepts I am familiar with, RPC, and happily create resources and work on designing the data model. There are many frameworks available now for building REST APIs. The problem is, they only provide the first two of the three important pieces. The resource representations, in my opinion, is the key item.

Why Do You HATEOAS Me?

I recently had a conversation with someone who gives regular talks on REST and semantic web technologies. He helped set me straight. I asked, “How do I explain HATEOAS to someone else?” The response was easy. He said that anyone that uses a web browser already does, they just don’t know it. For example, we want to read the news, so we type a well known URL into the browser. This is usually just the domain of the news service. We can equate this to publishing our web service endpoint URLs. Once you navigate to this page, the server serves up content that contains embedded links to other news articles from the same website, as well as links to other websites. I read the content and decipher which link I want to follow based on the contextual information provided with the link. These links are HATEOAS. The hypertext provides meta-data that describes their purpose and I use my brain to decide what to do next. Sometimes the server helps guide me in the right direction. I follow a link to a news article, then it provides a link to the next page of the article or allows me to jump around the various pages by use of pagination. The server doesn’t control where I go, but instead “suggests” what the next step is. Our RESTful APIs must work the same way. The only difference is that the “client” is a machine.

REST is a style that simplifies the interaction between client and server. This is great, but also deceptive. Like most things, the simpler the design the more difficult it is to do well. I believe that 80% of your design effort should be spent on resource representations. These are your “engines” that allow a client to interact with your API. They must not require the end user to read a volume of documentation in order to understand. It is the same as my yard trimmer that requires me to know that I have to purchase line refills instead of trying to wind the line myself. I’m like a four year old and a fishing rod, it always ends up in a nest of uncontrollable wire. This understanding, referred to as out-of-band knowledge, prevents your API from being useful. Developers have a hate-hate relationship with documentation. We hate to write it, but bitch incessantly when it doesn’t exist. The only knowledge that should be required is understanding the media-type of your representation. The client must understand what it wants to do, but shouldn’t need to know how to build up URLs to gain access to a specific resource. The service endpoint URL must return hypertext to point to the interesting resources. The resources themselves should provide hypertext to help the client know what else is available or suggest new states to the client. If you are thinking about business rules first and representations second, you have the order wrong. The client controls his state. This lends itself to a scaleable architecture because the servers don’t need to track the state of each client, that is the job of the client.

Ditch The Add Ons

In the end, we don’t need to build a better mousetrap or yard trimmer, but instead embrace the web as it was designed. Just like those after market parts designed to be bolted on to fix one problem, they are only useful for gas trimmers causing yet another problem. Think of how SOAP tightly couples the client to the server. The web is the most successful software we have ever seen. We should focus on why the web is successful and implement our RESTful APIs the same way. Document the media-types of your representations or use standard media types such as Atom. Otherwise we end up in RPC land with POX (plain old XML) that inevitably starts the versioning conversation. It is okay to version, but remember you are versioning the representations and not the service. The uniform interface sets us free. It is the one trimmer that doesn’t piss me off.

Donald Smith is a Software Architect at VUELIVE, Inc. You can follow Donald on Twitter @donaldlsmithjr

Be Sociable, Share!


Comments are closed.