Subject: Re: [Jmap] Call for objections - standardising on plural names everywhere

From: Stan Kalisch <[email-masked]>
Date: Sun, 3 Dec 2017 13:15:03 -0500

> On Nov 28, 2017, at 10:24 PM, Neil Jenkins <[email-masked]> wrote:
> 
> For completeness, copying to the list another suggestion from the GitHub ticket:
> 
> Mailbox.get
> Mailbox.getUpdates
> Mailbox.getList
> Mailbox.getListUpdates
> Mailbox.set
> 
> (You could also replace the "." with a slash, e.g. "Mailbox/get", which I think I slightly prefer for readability.)

I like this.  I think the hierarchical nature of the syntax actually makes the plural now more desirable than the singular and walks the reader of the spec through the idea that each of these actions is to be applied to multiple items, which of course is what you wanted in the first place.

> Not sure what response names you would use with this.

I'm not entirely sure at the moment, either, but ideally something else nice and hierarchical.

>> I, too, find it less awkward without the double-plural, but sticking with
>> only singular or only plural is still a vast improvement.
> 
> I'm not overly concerned which one we pick. If there's a general preference for singular over plural, I'm happy to go with that. The main thing is it's consistent.

Yes.

Thanks,
Stan

> The reason I picked plural is because the methods all operate on multiple items at once, but I agree it is slightly more awkward when combined with other plural words.
> 
> Neil.
> _______________________________________________
> Jmap mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/jmap

---

From: Ken Murchison <[email-masked]>
Date: Sun, 03 Dec 2017 13:25:23 -0500

I’m fine with plural. It’s just syntactic sugar anyways. 

--
  Kenneth Murchison
  Cyrus Development Team
  [email-masked]

On Sun, Dec 3, 2017, at 01:15 PM, Stan Kalisch wrote:
> 
> On Nov 28, 2017, at 10:24 PM, Neil Jenkins
> <[email-masked]> wrote:>> For completeness, copying to the list another suggestion from the
>> GitHub ticket[1]:>> 
>> Mailbox.get
>> Mailbox.getUpdates
>> Mailbox.getList
>> Mailbox.getListUpdates
>> Mailbox.set
>> 
>> (You could also replace the "." with a slash, e.g. "Mailbox/get",
>> which I think I slightly prefer for readability.)> 
> I like this.  I think the hierarchical nature of the syntax actually
> makes the plural now more desirable than the singular and walks the
> reader of the spec through the idea that each of these actions is to
> be applied to multiple items, which of course is what you wanted in
> the first place.> 
> I'm not entirely sure at the moment, either, but ideally something
> else nice and hierarchical.> 
>>> I, too, find it less awkward without the double-plural, but
>>> sticking with>>> only singular or only plural is still a vast improvement.
>> 
>> I'm not overly concerned which one we pick. If there's a general
>> preference for singular over plural, I'm happy to go with that. The
>> main thing is it's consistent.> 
> Yes.
> 
> 
> Thanks,
> Stan
> 
>> The reason I picked plural is because the methods all operate on
>> multiple items at once, but I agree it is slightly more awkward when
>> combined with other plural words.>> 
>> Neil.
> _________________________________________________
> Jmap mailing list
> [email-masked]

Links:

  1. https://github.com/jmapio/jmap/issues/164

---

From: Neil Jenkins <[email-masked]>
Date: Thu, 07 Dec 2017 16:42:17 +1100

So, thinking and talking to people about this a bit more, I've decided
that I prefer the following:
getMailboxes          -> Mailbox/get
getMailboxUpdates     -> Mailbox/changes
getMailboxList        -> Mailbox/query
getMailboxListUpdates -> Mailbox/queryChanges
setMailboxes          -> Mailbox/set

The response name is *the same* as the method call name.

My reasoning:
 1. Properties that reference other objects use the singular name (e.g.
    threadId property on an email). This makes no sense to be plural, so
    better to standardise absolutely everywhere on singular, as everyone
    agrees we should use just one or the other.
 2. The (non-error) response name being the same as the method name
    simplifies the spec and means you don't need to know how to
    conjugate English verbs to derive the response names for methods.
 3. The form is clear and easy to refer to standard types of method
    calls (e.g. a standard /get call).
 4. I used "changes" instead of "updates" because it differentiates it
    from the crud (create, *update*, destroy) part of /set.
 5. I used "query" instead of "list" because it's less ambiguous and a
    closer to match to what's happening.
Example fetching from/date/subject for first 10 threads in Inbox (which
also has Message renamed to Email as discussed before):
    [[ "Email/query", {
      "filter": { inMailbox: "id_of_inbox" },
      "sort": [ "receivedAt desc" ],
      "collapseThreads": true,
      "position": 0,
      "limit": 10
    }, "t0" ],
    [ "Email/get", {
      "#ids": {
        "resultOf": "t0",
        "name": "Email/query",
        "path": "/ids"
      },
      "properties": [ "threadId" ]
    }, "t1" ],
    [ "Thread/get", {
      "#ids": {
        "resultOf": "t1",
        "name": "Email/get",
        "path": "/list/*/threadId"
      }
    }, "t2" ],
    [ "Email/get", {
      "#ids": {
        "resultOf": "t2",
        "name": "Thread/get",
        "path": "/list/*/emailIds"
      },
      "properties": [ "from", "receivedAt", "subject" ]
    }, "t3" ]]

with response:

    [[ "Email/query", {
        "accountId": "1",
        "filter": { inMailbox: "id_of_inbox" },
        "sort": [ "receivedAt desc" ],
        "collapseThreads": true,
        "state": "abcdefg",
        "canCalculateChanges": true,
        "position": 0,
        "total": 101,
        "ids": [ "msg1023", "msg223", "msg110", "msg93", "msg91",
        "msg38", "msg36", "msg33", "msg11", "msg1" ]    }, "t0" ],
    [ "Email/get", {
        "accountId": "1",
        "state": "123456",
        "list": [{
            "id": "msg1023",
            "threadId": "trd194",
        }, {
            "id": "msg223",
            "threadId": "trd114"
        },
        ... etc...
        ],
        "notFound": null
    }, "t1" ],
    [ "Thread/get", {
        "accountId": "1",
        "state": "123456",
        "list": [{
            "id: "trd194",
            "emailIds": [ "msg1020", "msg1021", "msg1023" ]
        }, {
            "id: "trd114",
            "emailIds": [ "msg201", "msg223" ]
        },
        ... etc...
        ],
        "notFound": null
    }, "t2" ],
    [ "Email/get", {
        "accountId": "1",
        "state": "123456",
        "list": [{
            "id: "msg1020",
            "from": [{ "name": "Joe Bloggs", "email":
            "[email-masked]"}],            "receivedAt": "2017-11-01T14:03:01Z",
            "subject": "Let's talk JMAP"
        },
        ... etc...
        ],
        "notFound": null
    }, "t3" ]]

I have updated the pull request with the new form:
https://github.com/jmapio/jmap/pull/166 – I'll leave it a few days just
in case there are any final comments on this, then merge.
Neil.

---

From: Josef 'Jeff' Sipek <[email-masked]>
Date: Thu, 7 Dec 2017 10:10:16 -0500

>     agrees we should use just one or the other.

Good.

>     conjugate English verbs to derive the response names for methods.

Good.

>     calls (e.g. a standard /get call).

Good.

>     from the crud (create, *update*, destroy) part of /set.

Fine by me.

>     closer to match to what's happening.

Alright.  I thought that list (with optional filter) was plenty clear.
Would calling it "search" instead be even clearer?

Jeff.

-- 
A CRAY is the only computer that runs an endless loop in just 4 hours...

---

From: Neil Jenkins <[email-masked]>
Date: Fri, 08 Dec 2017 13:09:59 +1100

On Fri, 8 Dec 2017, at 02:10 AM, Josef 'Jeff' Sipek wrote:
>> 5. I used "query" instead of "list" because it's less ambiguous and a>>   closer to match to what's happening.
> 
> Alright.  I thought that list (with optional filter) was plenty clear.> Would calling it "search" instead be even clearer?

Yeh, we considered all these options. Bron didn't like /search to avoid
any potential for confusion with the IMAP SEARCH command (which doesn't
do sorting etc.).
I think /query is a good name, but /search is also fine. I don't really
care, and I suspect this is the common opinion, so I just picked one
which seemed to have a very slight advantage. If someone has a strong
argument for one, I can change it…
Neil.

---

From: Stan Kalisch <[email-masked]>
Date: Thu, 7 Dec 2017 22:18:15 -0500

> On Dec 7, 2017, at 9:09 PM, Neil Jenkins <[email-masked]> wrote:
> 
> Yeh, we considered all these options. Bron didn't like /search to avoid any potential for confusion with the IMAP SEARCH command (which doesn't do sorting etc.).
> 
> I think /query is a good name, but /search is also fine. I don't really care, and I suspect this is the common opinion, so I just picked one which seemed to have a very slight advantage. If someone has a strong argument for one, I can change it…

I'm not opposed to /search, but I think /query suffices.  As for the rest of it, it looks fine to me.

Stan