[Jmap] Review of draft-ietf-jmap-rest-00

[Robert Stepanek <[e-mail]>]

I just reviewed draft-ietf-jmap-rest-00. I do have no opinion on the need for the JMAP REST API, but it seems to fulfill a need (but see my remarks about section1). My comments mostly are about presentation:

1.
I could not understand from the Introduction in what cases REST would be preferred. I can imagine they are use cases, but the intro left me uncertain on what they would be. Maybe provide one or two examples?

1.2.1
“the simplified JMAP REST API”. Is that the “Simplified JMAP REST API” or just the “JMAP REST API”.

1.3
“The JMAP Session Resource will be extended by the following property” -> “This specification defines a new property for the JMAP Session Resource type:

1.3
THE URL MUST contain the variable  -> The URL MUST. Maybe also try to separate the two remaining capitalized words?

1.3
“Only properties that are a subset of the types String, Number, Boolean and arrays (as defined in [RFC8620] Section 1.1) can be referenced as variables”

Question 1: referenced in what way? Is this related to ResultReferences?
Question: 2 Is subset appropriate here?
Remark: It isn’t the properties, but their values that must be one of String, Number, ..

Maybe also state that property values of type object MUST NOT be used, as it seems as if any but objects are allowed?

2.
The request typically consists of a single JSON-encoded Request object

-> What do non-typical Requests look like? Why is it useful to state what typical is and can you be sure that this is going to be the case when this spec is in use by more people?

The method call id in the Invocation object of JMAP Responses to JMAP REST requests SHOULD be set to empty string

-> I did not know that empty strings even are allowed as method id, but looking at RFC 8620 it indeed seems legit! Do you expect issues with existing JMAP implementations that might expect ids to be non-empty?