Why is it not REST-based? - Commentary

[piboistudios]

In the FAQs section, under the question, Why is it not REST based?

There are mainly two reasons pointed out:

• REST does not support batching
• JMAP is transport agnostic (it's not really by the way? It just supports HTTPS and WebSocket transports)

REST doesn't support batching, but it is protocol agnostic and generally protocol servers can implement batch requests somehow, some way (at least, HTTP ones can, and most REST services are over HTTP). OData has already solved this for their RESTful spec; you can just have some batch endpoint that accepts a multipart/mixed content type with a series of application/http bodies resembling HTTP requests.

While this isn't a readily available feature for all or even most HTTP clients, most HTTP clients and servers feature an HTTP message parser which one can pretty much just utilize to implement themselves pretty easily on both sides.

A custom websocket protocol is perhaps understandable (even though, one of the major points of JMAP vs. IMAP is that JMAP is stateless and doesn't require a persistent connection), but I guess my frustration is that I see JMAP as a protocol with a good amount of potential, and the biggest barrier is lack of available implementations (that are production ready). This wouldn't be a problem if the core protocol utilized REST design principles and exposed an OpenAPI, which would significantly cut down on the learning curve as well, as most developers looking to build an API for email are probably familiar with REST and OpenAPI clients.

Also, on batching again: I understand JMAP batching is a bit more complex than just batching requests, as it also allows substituting response variables into subsequent requests, but, this is again something one could easily implement, custom string interpolation and templating setups are basically all the rage these days as I understand it. After all, I would much rather be able to just install some JMAP framework (or just generate one out from the OpenAPI schema if one didn't exist) and have to tinker with my HTTP server library to support batch requests properly than have to implement the entire protocol basically myself because people don't feel like writing open source implementations (and keeping them up to date; which would also be easier if JMAP had OpenAPI schemas)

Given this, if I want to use JMAP, I effectively have to write my own client and server side implementation, which leaves me wondering.. why wouldn't I just write a RESTful adaptation to JMAP that does exactly what I've just described to handle batching?

I could even use an OpenAPI schema to generate out a JSON:API server/client setup and just run that over WebSocket (most JSON:API implementations support typed server/client generation from some schema- or at least the most popular one for node.js does), and voila, I basically have an HTTPS and Websocket transport with mostly identical client APIs, much like JMAP.

The high-level goals of JMAP are not only good, but arguably much needed in today's world of email, where most people are using webmail solutions, which is creating this sort of walled-garden effect on a protocol originally intended to be a decentralized service to all; and even the design of the underlying server spec itself is probably optimal (it was clearly thought out by someone with much experience with webmail, part of why I like the spec, it removes a lot of thinking for me as a developer).

But there is sort of a weird clash between JMAP's goals and the specification. Like the main point is to create a web standard, and yet it foregoes using existing web standards for arguably no real reason.

This doesn't even get into the fact that REST data format-agnostic, which would enable developers to utilize even more bandwidth friendly data formats than JSON (but I suppose that would kill the J in JMAP).

I just think this is worth pointing out, not that I'm the first to point it out, hence the question is in the FAQs section. But some nights, thinking about this keeps me awake, and I felt perhaps posting this would help me get some REST 🥁tss

[rjbs]

As you say, you are not the first person to ask, but the answers have been provided! Also, there are years of mailing list archives at the IETF where past discussion can be seen.

Personally, I'd also say that my experiences with both JMAP and other "path-based" REST-ful APIs lead me to think that the usability of automatic API toolkits would be pretty lousy for any non-trivial JMAP work. Sometimes, people have asked, "What would it be like to put a path-based adapter in front of a JMAP server for simplified access?" The answer, so far, has been "Maybe it would be cool, but it isn't worth it, because a real JMAP client is easy enough to implement."

In the end, I don't think I'm going to convince you to accept JMAP's design in your heart by arguing, though. You'll get there, I hope, by writing software. 😉 Others have, and that's part of why there is JMAP software, meaning it continues to grow as a viable replacement for IMAP. Some new path-based solution would be starting from zero — another strike against it.

I hope the post does help you ʀᴇꜱᴛ easy, and maybe having slept on it, you'll wake up enthused to write some JMAP code and love it. If that doesn't work out, we at least wish you pleasant dreams! 😴

[piboistudios]

Haha, I don't mean to argue about it. This just stuck out to me for some reason, I check out https://jmap.io periodically, not sure if it's new or what, but as I was reading it this time I was just like "Hm... well.."

At the end of the day, I will probably end up having to roll my own JMAP implementation anyways for compatibility purposes if I do build some commercial webmail product as I somewhat dream to do, so when I am adapting it to an OpenAPI, probably the work will happen in parallel and if there's a point at which I'm like "Oh, this won't work", I'll report back here in case anyone else comes under the faulty impression OpenAPI is a better alternative to a custom messaging protocol. 😎

To clarify, I don't have any problems just using JMAP, I am just frustrated that there are still no viable node.js implementations and I have personally never had an experience with a JMAP email client (I once tried the demo but it didn't work; seems there's more implementations these days, so maybe I'll try them and report whether the experience is optimal).

I guess in terms of internet standardization time, 4 years isn't very long, just feels like it is taking a long time for wider adoption, which I'd like to see more of, and there is the nagging feeling I have that if it were an OpenAPI spec, it would be literally everywhere by now 😆 Existing webmail clients these days are kind of middling in the UX department by 2024 standards.

[piboistudios]

Oops, I just realized I said JSON:API several times when I actually meant JSON-RPC.

And, there is OpenRPC for generating clients/servers from schemas 😎

So basically what I plan to do is borrow the JMAP spec for an OpenAPI and OpenRPC adaptation alongside a compliant JMAP implementation. Will report back (probably in many years from now if I ever actually do it) with findings/learnings.