I think I finally understand the value of HATEOAS

First, a disclaimer. This post is about me solidifying some understanding I think I have achieved. I am still learning here, so some of this is likely wrong or the wrong interpretation. Take it with a grain of salt. If you know better, feel free to politely tell me what I got wrong in the comments. Thanks!
I have spent a lot of time in my study of “REST” thinking that HATEOAS is just something that people who like to over-engineer would use. I could not understand the value of just including a link to the resource in its payload, as most examples of HATEOAS do to demonstrate. I mean, it is nice to have it when you get a list of resources, but…
I understood that there might be some value in creating links to actions but I did not understand how it would make sense to maintain that kind of flexibility. It felt like it would cost way more than it would save. Even if you were taking a long view. Who would build a magical client that would just figure out what it all meant?
But I had an epiphany. It is not about future proofing or some magical client. It is about communicating business options to the client. It is taking your “REST API” and making it more than just a fancy database interface with CRUD operations.
Suppose I am creating an API for a conference submission application. The basic operations are fairly clear. I need to be able to accept a submission, show a list of submissions, and show a single submission.
But there are other things a user of my API needs to be able to do:
  • Edit a submission, if they own it.
  • Add a vote to a submission, if they are an organizer reviewing the submissions.
  • Delete a submission, if they have the right to do so.
  • Accept the submission for the conference, if they are an organizer.
There could be more operations, but this is a pretty good starting point.
Obviously, some of these operations require authorization. You still need to secure your endpoints and prove the user can do the thing they are trying to do. Don’t get caught up in that. We can assume that your endpoint and infrastructure know how to keep people from doing things they are not allowed to do.

Standard Case
Any old user/client sends a GET to http://example.com/api/submissions/0001, they get this back:
From this, you can see that the only valid operation they can perform is retrieving the submission.

“Author” Case
If I am logged in to the site (I’ve been given a security token, for example), when I send a GET to the same endpoint for a talk I submitted:
Now I see that there is an operation I can perform – “change-submission”. In my client code, I can look at the list of links to see if I should allow the user to edit the submission. I don’t have to know the logic for allowing submission – the server has already figured that out and told me I’m allowed to edit. I do need to know what “change-submission” means, so has to be a part of the contract and documentation of the resource.

Organizer Case
What if I’m an organizer?
Right now, I can only vote. While voting is open it doesn’t make sense for me to accept the submission. The client doesn’t need to know those rules, it only needs to look at the links to see what options it should present.

Now that I understand that HATEOAS gives me a way to let the client know what it can do without it having to have any knowledge of my services internal rules, I see the value. It is clear to me that if you find yourself in a situation where HATEOAS feels like more overhead than it is worth, you probably have a CRUD API. That might be OK. But it is good to know where you are.

Danzig on Delivering Software


Yeah, can you keep them in the dark for life
Can you hide them from the waiting world
Oh mother

Danzig’s “Mother” has always been to me a song about parenting. His threats to expose your kids to his world are hollow if you have done a good job and prepared your kids. He is right that your kids will never be ready for such a world without preparation. You prepare them by exposing them to elements of it in a controlled way.

Vaccination is the same idea. You expose a person’s body to a small amount of pathogen turned non-threatening. The pathogen triggers a response so that the body can build antibodies. When the person comes in contact with that pathogen later, those antibodies help them fight it off.

The same can be said for software. You will never know if it is ready for the world without getting it in front of actual users. Betas are as old as software itself, but they are no longer enough. Software has become too complex to take finished software to a few customers and find if is ready for the world. There are too many unknown cases where bugs can hide. Users expect software to be usable as well. It is hard to fix usability once the software has hit beta. You might be able to make some tweaks, but you can’t make systematic changes.

You need to put the software in front of real users often. This helps you see that the quality is there. You can’t repeatedly put unfinished work in front of users and expect them to believe you. You have to get it to done. If the users can use the software, you will see if it is usable. You get this feedback early enough to make changes if you discover major problems. Even small tweaks are cheaper when you can make them before things are completely solid.

Do like Danzig says. Give your software exposure to the real world as often and safely as possible. Then it will be ready when you let it out.

How We Design


Nadine asked, “Walk me through your design.”

Charlie started, “Well, first we contact the GPS satellites. We need current location and time. Then we reference the map provider to determine the features around us. If there is a mountain casting a shadow or a tunnel, we make note of it.”

Nadine nodded. “Interesting approach,” she said. “Please continue.”

Charlie continued on. “Next we consult the Naval Observatory to find out when the sun rises and sets. After that, we consult AccuWeather to get current weather conditions.”

At this point, Nadine can’t take any more. “Why didn’t you just use the photo resistor to see if it was dark? Isn’t that all you need to figure out if you should turn on the headlights?”

On Reporting


“We need to give the customer a report…”

If I had a dime for every time I heard that, I could at least buy a cup of coffee. We assume that customers like to stare at raw data, try to make decisions from it, and then go change something. I doubt that.

Reports fall in to a few broad categories:
• Lists of items that I need to do (pick lists, for example)
• Data I need to submit to a bureaucrat (tax forms)
• Summary information that tells me the current state of affairs (balance sheets)
• Raw/semi-processed data to make a decision (inventory on hand v. demand, as a contrived example)
In the case of lists, sometimes the best way to present the information is as a list report that we display on a screen or print. Then the user can take that report and use it to do their work, checking off items as they go. For simple cases and short lists, this is a fine solution.

The problem is, if they want to generate a list from a computer, it is a long list. It might even be a list that several people are working on. Reports are a horrible solution in this case. It is better to have a real application that can take into account things like changes to the list, work other people are doing, etc.

In the case of data to submit, just about every possible recipient of this data can accept a data feed. We can do this in the form of a report, but often it is better to just build up an automated interface.

When we need to give the user a summary of the current state, a report can be a pretty good solution. A well-formed report will have the information necessary for discussing the state with others. It can be portable (either by viewing it on a tablet or printing it out). It is concise and easy to find the information you need. These kinds of reports are rare. There are examples of mediocre attempts at this, so we know it is possible, but the reports that achieve this goal are a rare breed indeed.

The final case is happens a lot and I believe is the key problem with reports. We give the user some information, expect them to process it themselves, and then come back to our software to make some sort of change. We have turned the human into a computer that is subservient to a real computer.

Why does this happen? It happens because we are too lazy to do the analysis to figure out how the “algorithm” the human is using works. That might be because there are decisions made that are difficult to encode. It could be because we’re afraid we’ll get it wrong so we don’t even try.

Sometimes it is because we are afraid the user won’t trust our answer. There are ways to address this. We can show the user what we plan to do and allow them to confirm or override. We might have to display more information to the user so they can make that decision. Over time the user will trust the code and just let it do the work. At this point we have a happy user. To do this we need to iterate over the solution and get user feedback.

There are so many horror stories of how software makes people’s jobs harder. It’s ironic, because this software was sold to make their lives easier. We need to remember why we are building the software and do the hard things that will make our user’s lives easier. That is what they want.

Reusability is a Deal with the Devil


OK, it’s not, but it has some similarities… 🙂

Reusability sounds like a great thing. Build something and reuse it often. What’s not to like? Well, a few of things.

If you build something with the intent of being able to reuse it, by definition you are building more than you need right now. It takes extra effort to build in the extensibility points. You need to test for the hypothetical future cases.

There are cases where this extra effort is worthwhile. If you know you are going to be building a lot of similar applications the work you are saving yourself should offset the extra work. When you are building an interface to third party systems it makes sense to build in extension points. If your business is to build libraries for other developers, of course they need to be reusable. But these are rare cases and usually only need limited reusability.

If you have existing code and want to make it reusable, that effort has a cost. If the current codebase is not good, you will pay a lot to make it reusable, and not just immediately. The code will always be buggy because it started that way. To further tax the debt metaphor, you will pay interest on that code forever.

There are times when it might be OK to take current code and reuse it. In these cases you will want to copy and paste it into a new project. It should not keep any ties to its past life. It is serving a different purpose. The chance that it will solve the same problems is low. Trying to keep it in sync will just lead to more bugs.

If you really need to reuse code, you have to have automated tests around it. You need that safety net. Without it, as the code evolves away from its original purpose, bugs will creep in. A change to business logic to solve the current problem may have hidden impacts on other parts of the codebase. Automated tests will save you from a 4 hour hunt for that method you didn’t know existed because of a dependency injection trick.

If you need to get a feature done fast, reuse is your solid fair weather friend. Just be careful when the weather changes.