[vwelling]

I believe they're right in using POST, and here's why:

- Using GET with a request body:

Per RFC 7231, Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content, section 4.3.1 [1]: "A payload within a GET request message has no defined semantics; sending a payload body on a GET request might cause some existing implementations to reject the request."

Although you can argue whether or not you should be able to define the semantics of such a request body within the context of the resource, it quickly becomes moot in the face of reality: there's a good chance it won't work due to whatever client or intermediary is involved.

- Using non-HTTP verbs (i.e. REPORT, SEARCH):

Again, one can argue over their validity, but since most clients or intermediaries will not support them, there's little practical use. In this particular case, I'd recommend against them since most developers will not be familiar with them, making your API less user friendly.

- Using POST:

Per RFC 7231, Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content, section 4.3.3 [2]: "The POST method requests that the target resource process the representation enclosed in the request according to the resource's own specific semantics."

In other words, do whatever you want – such as executing a search query contained within the request body. This is semantically valid, widely supported and common practice. The only downside would be that caching of POST requests is not widely supported, although still possible. The spec even suggests an alternative solution: "Responses to POST requests are only cacheable when they include explicit freshness information (see Section 4.2.1 of RFC7234). However, POST caching is not widely implemented. For cases where an origin server wishes the client to be able to cache the result of a POST in a way that can be reused by a later GET, the origin server MAY send a 200 (OK) response containing the result and a Content-Location header field that has the same value as the POST's effective request URI (Section 3.1.4.2)."

In other words, you can implement a caching mechanism for your query resource that exposes itself through a URL structure, available for GET requests.

[1] https://tools.ietf.org/html/rfc7231#section-4.3.1

[2] https://tools.ietf.org/html/rfc7231#section-4.3.3

[dragonwriter]

> Using non-HTTP verbs (i.e. REPORT, SEARCH):

These are HTTP extensions, and are as much HTTP verbs as PATCH. The big problem is that REPORT and SEARCH are WebDAV extensions to HTTP, and their specs have WebDAV related baggage, and its at least as much "bad REST" to redefine the semantics of methods with existing standards as to use POST to get around the technical/practical problems with GET.

[vwelling]

Let me clarify, by non-HTTP I mean "not defined in the HTTP/1.1: Semantics and Content RFC" (RFC7231) and therefor not likely to be commonly implemented.

Could you elaborate on what you consider to be "bad REST" with regards to using POST in this case? The RFC clearly leaves the definition of the semantics of POST up to the implementation of that particular resource.

The only argument I could come up with, is that POST is not guaranteed to be idempotent or safe, whereas a search query would be. But a lack of guarantee doesn't exclude use cases where it would be.