JORM (Json Object-Relational Mapping) is not REST

To make this more transparent, let’s see how JORM and REST differ when we model a bank Api for viewing your account balance and transferring money.

It’s possible the Api is too simplistic but it’s a good place to start discussing things because this Api is missing some important things:

The first question is usually solved by something like Api Blueprint or OpenApi which provides documentation for a human to sift through, guess and try if GET /users/b2-d2 or GET /owners/b2-d2 provides the right data for the source of the transaction. It would be nicer and less error-prone if the Account-Representation would tell us where the data is but that is a somewhat-solved problem of JORM-Apis.

The second question is not satisfactory solvable because it always requires code duplication: If we can and are allowed to withdraw money or close this account is dependent on multiple business rules. A transaction is always possible unless the account is closed and unless the balance is below zero, but sometimes below zero is also ok but only up to a certain balance and so on. A client would have to implement the same rules as the server and always keep them in sync lest it allows something that the server rejects.

REST solves these problems, because REST publishes all the possible actions from the current state. A client can simply look at the list of actions and decide what to do next. It does not need to know nor care why an action is allowed and thus less information needs to be shared and almost no duplication occurs:

What is missing is the control for transferring money from a source to a target. It is missing because the account owner is on vacation right now and does not want any transfers. Or maybe it is missing because the account is closed. We don’t actually need to know the business reason. All our client sees is that the control is missing and therefore it cannot do it. We don’t need to duplicate why something is not allowed and that means Service A is free to add or remove rules whenever it wants and the client, Service B, just needs to react to the presence of a control or its absence. This is a supremely powerful concept and why the relatively new REST-style from the year 2000 is better at decoupling teams than the older RPC-Style Apis. The cost is that the services require more protocol knowledge as Oliver Drotbohm describes. If we adapt his naming to include JORM and REST we get:

The client only having protocol knowledge gives us very clear benefits when we design a SPAs (Single-Page Applications) or need to support multiple devices such as iOS or Android.

The clients just need to look for the existence of the "coolb:close-account" or the "coolb:transfer-money" to know they should display the buttons for closing or transferring money. They ignore controls and optional fields they are unfamiliar with or render generic widgets based on the inputs the server requires.

All in all a lot less code is required for each client, because the server controls the interaction and you have a lot less errors to deal with because your iOS, Android or Web Apps cannot mismatch state.

If that seems far-fetched then please consider that you are viewing this post in your browser that allows you to react to arbitrary content without Mozilla, Google, Apple or Microsoft making adaptions in their client.

All your browser has is the protocol knowledge and that is enough. If we design our Apis the same way the web is designed, then we get the same decoupling and scalability benefits that have powered the last 30 years. This is not surprising because Roy Fielding’s dissertation, which defined the REST architectural style, was defining the core properties of HTTP so they knew which changes would benefit the protocol.

By now it should be clear why REST has clear benefits and why a small but vocal group (so called RESTafarians) take every opportunity to point out that most street-REST is not REST (REST: I don’t Think it Means What You Think it Does).

It seems that this grouped has switched to using the name Hypermedia and Hypermedia Apis when talking about actual REST though. Semantic diffusion has taken its toll but since the ideas are so great and there is a dissertation describing them it is worth bringing back the term REST. For that to work we need a name for the alternative, and since that alternative is close enough to what many object-relational modelling tools give us, the name for the alternative is simply JORM.

Now for the real question: should everyone adopt REST over JORM?

I think the sweet spot is when teams own their server (backend) as well as one or more clients (frontend: SPA, iOS or Android app). When they adopt REST, they can make their clients significantly dumber and by that not only save a lot of code but also iterate faster because their client is decoupled from their server.

Sadly it is less clear for company-wide or even public Apis for two reasons:

REST Apis make it very easy to solve problems because the server exposes all allowed actions in the form of Hypermedia Controls. That however means you have to somehow know the problems your clients want to solve, which requires more work than just exposing state and letting them figure it out.

The second problems is that most clients are not used to the discoverable nature of REST Apis and demand stable URLs. Even without documentation teams often try to retro-engineer the URLs and when they inevitably change, their clients break, which is what Hyrum’s Law describes:

That however means the Apis cannot evolve as intended which is why solutions like FIT URLs are proposed where all your URLs are signed and any mismatch leads to a 404 Not Found.