Carrying water
or, Why are you giving this to me?
Last post I mentioned bookkeeping on the client side for the server: taking raw input from the user and transforming it into something the server API understands in the browser’s JavaScript. This sort of intelligence shouldn’t be expected of the client code.
There are other cases where the server gives data to the client, which the client is expected to regurgitate back to the server in subsequent requests. The client handles that data either passively or actively.
In the passive case, the data in question represents some sort of processing state. In a stateless protocol like REST, the client is expected to hold on to processing state and return that information back to the server. This means the server doesn’t have to hold session information.
Take, for example, surrogate keys. A surrogate key identifies an entity or resource as maintained by the server. The servers assigns the id to a created resource, and that id is later used and is needed by the client to identify the resource to update, delete, or read. The resource id is a processing state, indicating that data has been stored on the server.
Order status is another processing state, but in this case, should the client be burdened with holding onto order status? It depends on whether the user ever sees that status in the UI. If not, then what purpose does does it serve to pass order status back and forth via HTTP? Surely, the status of the order has to be stored on the server; it can be retrieved by knowing the order id. So this is a case of passive but possibly unnecessary state transfer.
Another case is where the server returns shipping information about an order item, and that includes shipping methods. The user selects methods based on description, which originates from data stored on the server. Perhaps the server also associates a shipping method id with the description. Imagine an API where it is expected that if the user changes the shipping method, the server is notified by id of the new method. There has to be a bit of logic on the client to know to pass on the method id, not the user-selected method description.
In practice, it isn’t difficult to display the description as option text and store the id as the option value (which is not visible). The shipping method options are, in effect, resources with surrogate keys. The problem with leaking ids, though, is that it is a temptation to write logic on the client based on those ids.
If Method X is later dropped from the options, does anybody go back and clean up the client logic based on it’s id (42)? How would you know about it and how to find it? Numbers appear everywhere in code. If there is a lot of logic based on ids, then 42 may appear in other context unrelated to shipping methods. More that likely, the unnecessary logic will remain, leaving future maintainers to have to at least parse through it mentally. Little things like these add up.
Symbolic keys, such as “METHOD_X” can be used instead of ids. The disadvantage of symbolic keys is that they’re another data fragment to maintain, and another index to search by (or a map maintained somewhere in code).
Why not use the description? It is a natural key. In the past, we would worry about performance on string comparisons in an index, but unless you have billions of these records, the impact nowadays is negligible. If logic based on the string values creeps into the client code, it’s easy to find. Descriptions do change, sometimes, but I would argue that if the description changes, the meaning does, too, and so any logic impacted should be re-examined.
Next post I will discuss active bookkeeping of server data on the client.
