Don't build a general-purpose API to power your own front end
We have an API similar to this.<p>I&#x27;d say, it can make sense. But one big issue is how it muddies the line of where certain frontend decisions should be made. For example; if you have a person&#x27;s profile picture, and you want to round it, should that be a property on the JSON structure? E.g.<p>{ &quot;profilePicture&quot;: { &quot;url&quot;: &quot;<a href="https:&#x2F;&#x2F;mycoolpicture.com&#x2F;pic.jpg" rel="nofollow">https:&#x2F;&#x2F;mycoolpicture.com&#x2F;pic.jpg</a>&quot;, &quot;rounded&quot;: true } }<p>Or a property of how the frontend transforms that structure into HTML? In other words, its an opaque, intrinsic property of the &quot;profilePicture&quot; &quot;JSON-component&quot;, every profile picture is rounded, because that&#x27;s just how profile pictures are.<p>Until you hit the one page that wants one that isn&#x27;t. No problem, maybe a generic &quot;picture&quot; &quot;JSON-component&quot;. Or you hit the page that needs a squircle. Ok maybe we do need a &quot;border&quot; field, and why not just make its value the same as the CSS `border` property and oh my god are we just reinventing HTML?<p>There&#x27;s no right answer to this question, and it will appear in literally every single component you build. Maybe its text weight: How generic should it be? Very-generic: &quot;title&quot;. Kinda-generic: &quot;heavy&quot;. Or literally just CSS.<p>What do these styles mean when faced with user browser preferences, such as dark mode or accessibility systems? By the API contract, &quot;cardTitle&quot; means &quot;roboto, 16px font, #0000ff font, whatever&quot;; but not always, right? Does the frontend disobey the contract? Do you send these preferences to the backend and let it handle it? Does the contract allow for lee-way in how its responses are interpreted? How much lee-way?<p>Lets say I want a sidebar. That sidebar has six items, so we list them. But what happens when the site is displayed on a phone? Well, for the sake of just providing an answer to continue this line of thinking: the designers want it to become a bottom bar. No problem, except, uh, the API says it should be a sidebar and we&#x27;re not really communicating how big the screen is to the API are we? Well, maybe we are, sure, we should have considered that during the v1. Is the server really the best source of truth on how many items a 976px wide screen can hold? Four maybe I guess? Maybe the frontend just sees `sidebar`, interprets it to &quot;understand&quot; &quot;implicitly&quot; that it means &quot;bottom bar&quot; on small screens, and do the best it can, and now the entire point of this exercise is out the window and we&#x27;re not obeying the API.<p>Another problem is during visual redesigns. This may demand the recreation of your entire API surface; you just doubled the work of a visual redesign. If the data model were generic, your backend team may not have even had to have been consulted.<p>Another is in interaction. Button which opens a new tab to google.com; easy, no problem. But in every reincarnation of this idea, I&#x27;ve never seen a strong argument for how to handle even a basic form, with a button to submit the input to another API endpoint. Do you have something like<p>{ &quot;form&quot;: [ { &quot;formTextField&quot;: { &quot;id&quot;: &quot;firstName&quot; } } ... { &quot;formSubmitButton&quot;: { &quot;endpoint&quot;: &quot;&#x2F;createUser&quot;, &quot;verb&quot;: &quot;POST&quot;, &quot;arguments&quot;: { &quot;id&quot;: &quot;firstName&quot; } ... } } ] }<p>How do you handle the response from &#x2F;createUser? What if there&#x27;s an error? What if one page that calls &#x2F;createUser needs to display the error in a snackbar, but another page needs to display it in-line with the button? Do you just... not do that? Just throw every error into a snackbar? Ok, are you capable of updating the local cache with the response from createUser, such that another call to the page-rendering API isn&#x27;t necessary?<p>This doesn&#x27;t feel as good to me as the rest of this line of thinking, which is already not great. It feels like &quot;we had this really cool idea to render our entire frontend in JSON, oh crap we need to support interaction patterns other than queries, uh, how do we shoehorn that into our cool idea, ok, hold my beer this is cute.&quot;<p>Look; there&#x27;s a reason why data and views are separate. This idea isn&#x27;t new. I hope you realize that, but I&#x27;m afraid you don&#x27;t; our industry does tend to revolve in cycles, but this is one that shouldn&#x27;t come back.<p>There are <i>really</i> specific use-cases for something like this which are actually powerful, from my point of view. The example from our app is, best put: imagine a google search results page. No interaction except simple hrefs. Maybe you have a ton of &quot;Link&quot; { &quot;title&quot; &quot;subtitle&quot; &quot;body&quot; } cards, maybe a &quot;MapResult&quot;: { &quot;latitude&quot; &quot;longitude&quot; }, basically displaying a list of cards which may have different content. The frontend needs to know how to render each card kind, but the specifics of how its rendered are kept presentation independent; nothing is asserted about structure, just content and relationships between the content. It can work for that. It still has problems, especially as the business wants more and more things shoved into this model that really wasn&#x27;t built for it, but it can work.<p>I know its a meme, or the buzzword of the day, or whatever, but: GraphQL is actually really good at solving the problems you think this solves. It doesn&#x27;t do it for free. You have to think about N+1s and composite queries and performance around those and designing a good schema. But, from the perspective of just the API language you&#x27;re talking, its actually pretty good. And if you&#x27;re really having performance problems on a page, you can always amp up your API caching, or introduce page-specific queries which collate data on the backend into a small number of database queries, or whatever.