HATEOAS and errors in production

Author: Alec Kornblum 2024-01-06 Sat 15:13

This article serves to codify my learning in the face of errors I have run into when deploying to production for aleckornblum.com. In particular, I have had trouble with part of the user experience: the first time experience!

The error-prone development workflow

I have been in a groove lately; developing several tools for aleckornblum.com.

As such, I've started to collect my thoughts on a "standard operating procedure" for development1. My SOP needs improvement, though.

As of today, it goes a little like this:

  1. Migrate my dev database and mock the new data
  2. Handle RCDU for the new data
  3. Refine the UI with any quirks or scripting I want (plots, UI scripting, lazy loading, etc.)

This should be familiar to anyone who has done simple web development. However, these three steps have not properly accounted for the user without any data in the system. I skipped that step for expedient RCDU programming by mocking the data.

In practice I have found that I frequently run into deployment errors in production. This is because in prod I typically just migrate the database and go. Without seeding the database, the result is unpredictable behavior with no data in the datastore. And seeding the database for all users would be impractical and unsustainable and idiotic.

This has impacted me recently while developing my shopping UI. Something similar also happened during the weightlifting UI development: I discovered my Dad's data mixed in with mine!

The proposed solution

The moral of the story is that the SOP might work better if it were:

  1. Migrate DB and mock data
  2. Handle RCDU
  3. Handle Multiple users and users with no data
  4. Refine the UI for any quirks (same as before)

The big difference is #3. This step should be when I utilize a test user without any data. This would provide an opportunity to refine my UI for non-data-having users.

Hypermedia and HATEOAS considerations

At this point it's important to consider hypermedia and HATEOAS. As I've learned from the good folks over at htmx, the only thing a user should need to get up and running on a website is a link to the initial page. Without my SOP step #3, a new user would have trouble to get up and running on my website (without out-of-band knowledge). Without step my SOP #3, I am assuming the user will figure out how to navigate to all required configuration pages and fill out his or her configuration before using each part of my UI. For example, aleckornblum.com/parking can be used to track where you've parked your car. However, it requires TWO configurations before it can function: /parking-decks and /cars.

The remedy I am considering is to eliminate the required out of band information for configuration. This involves SOP step #3. If done correctly, the UI for an unconfigured user should walk him or her through a first time configuration. The normal UI needs to be hijacked to provide redirections and instructions for a first-time-configuration. After following that flow, the user can be redirected back to the page, which should function normally. Instructions for inputting configuration data (and the fact that I am leading the user through a first time configuration) should be made obvious with headings and messages to the user. Hypermedia is special because it contains the information, the tools, and the instructions to the user to use them. That's the uniform interface.

I'm working on improving my own development processes to provide a high quality user experience for my 2 active users on aleckornblum.com: my dad and my wife!!

Check back for updates to see my progress!!



You can find my thoughts about CRUD programming here.