Subject: Re: [Jmap] JMAP Conceptual Decisions

From: Aki Tuomi <[email-masked]>
Date: Mon, 3 Jul 2017 10:30:23 +0300

On 21.06.2017 06:52, Neil Jenkins wrote:
> The short answer is it's good enough, widely understood and it's by
> far the easiest thing for developers to adopt. There's support in
> basically all OSes and programming languages. It's easy to read and debug.
Hi!

A comment about HTTP+JSON. When finalizing this decision, one should
consider the point that it would be a really good idea to consider
compability with swagger. Big businesses use swagger (and it's kind) to
generate thin client APIs, and choosing format that is not readily
mappable to these will reduce the business appeal to this API, or
requires someone to produce java/python/ruby/whatever binding(s).

We provide doveadm HTTP API using the current JMAP syntax, and this has
been one of the most frequent concern with the data structure from our
customers.

Aki Tuomi
Dovecot oy

---

From: Alexey Melnikov <[email-masked]>
Date: Mon, 3 Jul 2017 10:33:18 +0100

Hi Aki,

> requires someone to produce java/python/ruby/whatever binding(s).

For people like me who never used swagger, can you elaborate on what the restrictions are, so that the group can evaluate specific requirements?

Thank you,
Alexey

---

From: Aki Tuomi <[email-masked]>
Date: Mon, 3 Jul 2017 12:35:39 +0300

> For people like me who never used swagger, can you elaborate on what the restrictions are, so that the group can evaluate specific requirements?

The problem is, I guess, that most of these tools are geared into JSON
object concept. So each reply or request contains one or more JSON
objects. Not array of string,something,string tuple.

I am not sure if the problem with HTTP+JSON is so horrible with
performance that it requires bulking the requests, and to me it feels
bit like premature optimization.

For more detailed explanation, see
https://swagger.io/docs/specification/basic-structure/

Aki

---

From: Ted Lemon <[email-masked]>
Date: Mon, 3 Jul 2017 08:46:37 -0400

> bit like premature optimization.

It sounds from what you are saying as though swagger compatibility would preclude this optimization.

---

From: Aki Tuomi <[email-masked]>
Date: Mon, 3 Jul 2017 16:29:33 +0300 (EEST)

> On July 3, 2017 at 3:46 PM Ted Lemon <[email-masked]> wrote:
> 
> 

>From what I've gathered there is no simple way to express the current API in Swagger. This is itself not a blocker, one can write connectors without swagger too.

The current JSON format looks like it has been designed to benefit jmap<->imap connector. I am not convinced at the moment that "request bulking" actually provides such grand benefits, other than when you are making such connector where the order of requests makes a difference when sent to an IMAP server using IMAP protocol.

Concurrent access should not be a problem for a well-designed server, so one cannot really argue for ordering the requests either.

I would have raised these concerns earlier, but I was under the impression that the JSON format was already decided.

Aki

---

From: Neil Jenkins <[email-masked]>
Date: Tue, 04 Jul 2017 11:38:45 +1000

On Mon, 3 Jul 2017, at 11:29 PM, Aki Tuomi wrote:
> The current JSON format looks like it has been designed to benefit jmap<->imap connector.
No, it was primarily designed to minimise round trips and connection overhead, while maintaining consistency and usability.
>  I am not convinced at the moment that "request
> bulking" actually provides such grand benefits, other than when you are> making such connector where the order of requests makes a difference when> sent to an IMAP server using IMAP protocol.

In the "Structure of a request/response" section of my original email in this thread I gave an example where certain actions need to happen in a specific order to get the results the client wants. Round trip times (i.e. latency) make a huge difference in perceived performance, especially on mobile where even with good infrastructure your latency is higher.
> Concurrent access should not be a problem for a well-designed server, so> one cannot really argue for ordering the requests either.

Concurrent access is allowed with JMAP already. The issue is when you need to guarantee the order, as in the example above. Also, if you don't have HTTP2 you would be killed with the connection overhead at this point (you could easily get up to 100 requests needed just to show a list of the first 30 items in your Inbox once you have a separate one for each thread object, each mailbox object, each message in the threads etc.).
Autogenerated java/python/ruby/whatever bindings would be nice, but I'm reasonably confident that people will write them anyway once JMAP is a full RFC; it would not be difficult to do so. Dealing with the performance problems of a protocol that assumes clients are always within 10ms RTT of the server though would be much harder.
Neil.