The dogma of restful apis

When organizations are dogmatic about RESTful APIs -- e.g. a single endpoint relates to a single entity -- they inadvertently push the complexity of coordinating and combining data (data synchronization) to the front-end. This then requires complex "middle-end"¹ systems on the front-end to perform all the gnarly bits of data marshaling.

Why is this a problem? Someone has to write the logic for fetching and combining data, why not the front-end? This is how I rationalize pushing complexity to the front-end, but to what effect? Well, the front-end naturally becomes more complicated. Who more than anyone else complains about front-end complexity? API developers. You can have your RESTful ideal but that means you should stop complaining as much about front-end complexity. We need complex concurrent paradigms because data synchronization lives in the middle-end.

Instead of a 1:1 mapping between endpoint and entity, I would like to advocate for a 1:1 mapping between endpoint and page.

This recommendation is not an ideal, rather, a goal. There's nothing in RESTful design that says this isn't possible, it's merely the mindset that developers have that needs to shift.

I've worked on projects that require 10+ [GET] requests to render a single page. Most of the time these requests have dependencies. For example:

# Inbox page
[GET] /accounts
  foreach :account_id [GET] /accounts/:account_id/mailboxes
    foreach :mailbox_id [GET] /mailboxes/:mailbox_id/threads

Not only do we have the latency of making multiple network requests, but we also have to wait for some requests to finish before making subsequent ones. We also have to handle error states when one of those requests fail. These are non-trivial issues that contribute to complexity.

Instead we could do something like:

# Inbox page
[GET] /inbox

There is no longer a waterfall effect to making requests, the business logic of data synchronization rests on the API, front-end is much simpler, and we can even optimize the database queries for fetching this data!

This is one major reason why I believe graphQL gained popularity, it was a paradigm shift to move closer to a 1:1 mapping between endpoint and page.

Does it really matter that much to me? No because I enjoy the middle-end to the projects I work on. I just think it's hypocritical to on one hand complain about front-end complexity while unintentionally pushing that complexity to it.