Subject: Feedback on draft-ietf-httpbis-safe-method-w-body-02

From: "Slik, David" <[email-masked]>
Date: Thu, 20 Jan 2022 07:17:02 +0000

I have some initial feedback on the draft HTTP Query Method proposal.

https://datatracker.ietf.org/doc/draft-ietf-httpbis-safe-method-w-body/

After corresponding with the document authors, I have been directed to send my feedback to the IETF HTTP WG mailing list.

Document feedback:

1. Introduction

Moving query parameters from the request URI to the request body improves overall security, given that the request URI is often cached, stored, logged and otherwise potentially disclosed by intermediary systems. As a result, if PII or other sensitive information is included in the query section of an URI, it is at a higher risk when compared to when it is included in the request body.

A description of this advantage may be worth including.

2. Query

The resource that a query method targets is often a representation of a collection. As such, while technically correct, I would consider the statement, "The payload returned in response to a QUERY cannot be assumed to be a representation of the resource identified by the effective request URI." to be a little strong. Perhaps, "The payload returned in response to a QUERY MAY be a representation other than the resource identified by the effective request URI."?

The statement "If the response includes content, it is expected to describe the results of the operation." would be clearer if it was worded, "If the response includes a response body, it is expected to describe the results of the operation."

Regarding, "It is important to note, however, that such conditions are evaluated against the state of the target resource itself as opposed to the collected results of the search operation.", when the target resource is the collection, the conditions are evaluated against the entire collection (not just against the resulting subset, as you mention). This distinction may require additional elaboration.

3. The "Accept-Query" Header Field

The sentence "The order of types listed by the Accept-Query header field is insignificant." should be changed to "The order of types listed by the Accept-Query header field is not significant." Insignificant implies that there is a difference indicated by the order, but it can be disregarded, where not significant indicates that there is no difference indicated by the order, and it shall be disregarded.

4. Examples

I would encourage including an example with a JSON query request and response.

Here is an potential example that uses the draft IETF JSONPath query (https://datatracker.ietf.org/doc/draft-ietf-jsonpath-base/):

​4.3 Simple QUERY with JSON response

A GET for a JSON resource:

GET /books HTTP/1.1
Host: example.org
Accept: application/json

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{ "store": {
       "book": [
         { "category": "reference",
           "author": "Nigel Rees",
           "title": "Sayings of the Century",
           "price": 8.95
         },
         { "category": "fiction",
           "author": "Evelyn Waugh",
           "title": "Sword of Honour",
           "price": 12.99
         },
         { "category": "fiction",
           "author": "Herman Melville",
           "title": "Moby Dick",
           "isbn": "0-553-21311-3",
           "price": 8.99
         },
         { "category": "fiction",
           "author": "J. R. R. Tolkien",
           "title": "The Lord of the Rings",
           "isbn": "0-395-19395-8",
           "price": 22.99
         }
       ],
       "bicycle": {
         "color": "red",
         "price": 19.95
       }
     }
   }

A simple query with a JSON response body:

QUERY /books HTTP/1.1
Host: example.org
Content-Type: example/jsonpath
Accept: application/json

$..book[?(@.price<10)].title

Response:

HTTP/1.1 200 OK
Content-Type: application/json

[
   "Sayings of the Century",
   "Moby Dick"
]

Thanks,

David Slik
Technical Director, Astra Platform
NetApp, Inc.

---

From: Julian Reschke <[email-masked]>
Date: Thu, 20 Jan 2022 09:22:36 +0100

Thanks David!

Am 20.01.2022 um 08:17 schrieb Slik, David:
> <https://datatracker.ietf.org/doc/draft-ietf-httpbis-safe-method-w-body/>
>
> After corresponding with the document authors, I have been directed to
> send my feedback to the IETF HTTP WG mailing list.
>
> Document feedback:
>
> *1. Introduction*
>
> Moving query parameters from the request URI to the request body
> improves overall security, given that the request URI is often cached,
> stored, logged and otherwise potentially disclosed by intermediary
> systems. As a result, if PII or other sensitive information is included
> in the query section of an URI, it is at a higher risk when compared to
> when it is included in the request body.
>

Agreed; see <https://github.com/httpwg/http-extensions/issues/1895>.

> *2. Query*
>
> The resource that a query method targets is often a representation of a
> collection. As such, while technically correct, I would consider the
> statement, "The payload returned in response to a QUERY cannot be
> assumed to be a representation of the resource identified by the
> effective request URI." to be a little strong. Perhaps, "The payload
> returned in response to a QUERY*MAY*be a representation*other than*the
> resource identified by the effective request URI."?

Well, it will be something else most of the time. If it wasn't, we could
just use GET, no?

> The statement "If the response includes content, it is expected to
> describe the results of the operation." would be clearer if it was
> worded, "If the response includes a*response body*, it is expected to
> describe the results of the operation."

"content" is the correct term as per
<https://greenbytes.de/tech/webdav/draft-ietf-httpbis-semantics-19.html#content>.
(But we could hyperlink that).

> Regarding, "It is important to note, however, that such conditions are
> evaluated against the state of the target resource itself as opposed to
> the collected results of the search operation.", when the target
> resource is the collection, the conditions are evaluated against the
> entire collection (not just against the resulting subset, as you
> mention). This distinction may require additional elaboration.

I don't see a contradiction here. Note that "collection" is something
not defined in HTTP. If the target resource is a "collection", then yes,
the condition is by definition evaluated against the state of that
collection.

> *3. The "Accept-Query" Header Field*
>
> The sentence "The order of types listed by the Accept-Query header field
> is insignificant." should be changed to "The order of types listed by
> the Accept-Query header field is*not significant*." Insignificant
> implies that there is a difference indicated by the order, but it can be
> disregarded, where not significant indicates that there is no difference
> indicated by the order, and it shall be disregarded.

Agreed: <https://github.com/httpwg/http-extensions/issues/1896>

> *4. Examples*
> Here is an potential example that uses the draft IETF JSONPath query
> (https://datatracker.ietf.org/doc/draft-ietf-jsonpath-base/
> <https://datatracker.ietf.org/doc/draft-ietf-jsonpath-base/>):

I agree that more examples would be good. However, this would introduce
a dependency on a draft that is likely to be finished farer in the
future. Maybe there's a simpler-but-standardized JSON query language
that we can use (optimally with a defined media type...).

Best regards, Julian

---

From: "Slik, David" <[email-masked]>
Date: Thu, 20 Jan 2022 09:42:49 +0000

> Well, it will be something else most of the time. If it wasn't, we could

Fair enough, as the above property (where the query response is the same media type as the default GET media type for the URI) is only true for some types of queries.

> (But we could hyperlink that).

Guess I'm showing my 2616 age. :)

Thanks for the pointer to that draft. Nice to see all of the 723x RFCs, etc, being consolidated together.

> the condition is by definition evaluated against the state of that

Agreed.

Queries involving a "collection" (being structured content, typically in XML or JSON, following a specific schema where multiple entities are stored) are a very common use case for query, so I'll re-read the draft and see there are any other suggestions around this use case that we may want to consider.

> that we can use (optimally with a defined media type...).

Ah, I did not know that the timeline for draft-ietf-jsonpath-base was further out.

I will take an action item to draft another example based on something similar that is already approved.

Would you like me to open it as an issue in github, or send it to the mailing list for discussion first?

Thanks,

David Slik

---

From: Julian Reschke <[email-masked]>
Date: Thu, 20 Jan 2022 10:54:11 +0100

Am 20.01.2022 um 10:42 schrieb Slik, David:
> ...
>> <https://greenbytes.de/tech/webdav/draft-ietf-httpbis-semantics-19.html#content
> <https://greenbytes.de/tech/webdav/draft-ietf-httpbis-semantics-19.html#content>>.
> ...

Most :-). "HTTP/1.1" (the message format) is separate, so is Caching.

> Ah, I did not know that the timeline for draft-ietf-jsonpath-base was

It's just an assumption.

> ..

Both works for us. If we expect a change (like adding an example),
directly starting with a Github issue makes sense.

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Sun, 23 Jan 2022 22:55:12 +0100

On 20. Jan 2022, at 09:22, Julian Reschke <[email-masked]> wrote:
> future.

Unless the example is normative and not just an example, I don’t think that this would get in the way.
(And the jury is still out on the race between the two drafts.  You did start earlier :-)

> Maybe there's a simpler-but-standardized JSON query language

Well, you could use RFC 6901 JSON Pointer.

> that we can use (optimally with a defined media type…).

Thanks for the reminder!

Grüße, Carsten