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

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.