Isolating API data model differences and smells from application code
Single-page web applications typically communicate with at least one API to retrieve data and perform actions. Differences and “smells” from these APIs’ data models can spread through the application codebase if we allow them to.
In this post, I show a few examples and describe a simple approach to confining them to a small corner of the codebase.
Differences, inconsistencies, and poor choices
Each API uses a specific capitalisation style for JSON property names, usually
Property names can be abbreviated differently between APIs or even within the same API. Properties can also be named poorly, causing their meaning to be unclear and causing confusion — or they may simply be misspelt. Data types may be poorly chosen or applied inconsistently.
This made-up order object demonstrates some of these problems:
Fix the API
The best solution by far when faced with an API having these kinds of problems, is of course to fix the API. Doing so addresses the problem for all consumers, and also improves implementation code of the API. However, that may not always be possible — there may be existing consumers which the API needs to remain compatible with, or fixing it might not be a priority for the owner of the API, for example.
Practical solution — abstraction
So, we have to consume this API as it is, or we’re consuming multiple APIs which have different conventions. Adding a simple translation step immediately after parsing the received response allows us to normalise or tidy up the data at the first possible opportunity:
Now, we have a much nicer data object for use in the rest of our code:
The same cases as shown for response data above also apply to request data that our application builds up for sending to APIs. And the same pattern can be used to deal with it — perform translation immediately before sending the request.