←back to thread

Cognitive load is what matters

(github.com)
1457 points nromiun | 1 comments | 30 Aug 25 12:58 UTC | HN request time: 0.216s | source
Show context
schnatterer ◴[31 Aug 25 06:15 UTC] No.45080799[source]▶
> business logic and http status codes Why hold this custom mapping in our working memory? It's better to abstract away your business details from the HTTP transfer protocol, and return self-descriptive codes directly in the response body: { "code": "jwt_has_expired" }

While the logic behind it sounds reasonable, REST does the exact opposite with the same goal: simplicity, easy to learn, i.e. reduce mental load. I know there are other reasons for REST/SOAP/Graphql, etc. Still makes mental load a somewhat subjective matter to me.

replies(2): >>45080867 #>>45080938 #
1. hn_throwaway_99 ◴[31 Aug 25 06:32 UTC] No.45080867[source]▶
In my experience, though, a lot of "REST in the real world" failed at its lofty original goals, precisely because its original goals required too much cognitive load.

The reason REST largely succeeded (or, rather, what I like to refer to as "REST-lite") is because people who wanted to build stuff quickly on the web realized "Hey, I don't need all this protocol complexity (see: SOAP), I can just make simple, human-readable API calls over the same HTTP layer my browser uses anyway".

There is other stuff in "official REST" that I think has some value, like the noun/verb structure of API routes, but shoehorning API-level error codes into HTTP status codes has been a disaster IMO. Every time I've seen this done I've seen the same issues come up again and again and new developers constantly have to rediscover solutions and problem spots. Does "404" mean the API endpoint doesn't exist, or that particular resource doesn't exist? How do I map my very specific API error to rather generic HTTP status codes? Does a status code error mean a problem with the networking or the application?