Not everyone knows about it, but HTTP/2 brings some awesome sauce to the API scene (REST in particular in this case). It used to be with HTTP/1 that you wanted to reduce the number of requests made by the frontend and increase the size of the payloads because of network related performance costs.

However, because of HTTP/2’s performance enhancements through multiplexing, header compression and reuse, and server push, it is now extremely performant if not more performant to make multiple requests than a single large request. Indeed, combining the goodness of async & await with a bit of Promise.all([]) special sauce leads to a very workable solution for the frontend with few if any downsides. Through the generalization of endpoints, the frontend can reuse code that utilizes the endpoints which leads to a more modular and flexible design.

One of the main disadvantages with the HTTP/1, “network hack”, approach was a bunch of one-off endpoints that were very specific to a particular application. The HTTP/2 benefits to API design are immense since it allows endpoints to be decoupled from a particular application through a generalization of the endpoints thereby allowing full advantage to be taken of REST’s HATEOS resource linking, and thus attaining the holy grail of the Richardson maturity model.

In object-oriented design, the larger and more specific to a particular use case you make your objects the less reusable, the less cohesive, and the more tightly coupled they tend to be. The same is true for REST Endpoint design. Decoupling your application by writing endpoints that “do one thing and do it well” leads to a flexible architecture (similar to how smaller methods lead to better code) that is easier to test, extend, and maintain.

Endpoint specialization for a particular use case is the antithesis of endpoint reusability. These large endpoints are akin to “God Objects” that know and do too much and therefore they must be humbled a bit through a reacquainting with the harsh realities of modern APIs.

I could keep babbling on, but Phil Sturgeon also has a few sound words to say on the matter:

Includes, partials, etc., can all graduate to being actual brand new requests, instead of being some weird network hack because we were scared of handshake time.

Hear, hear!