The document discusses approaches for designing a RESTful search API that handles complex queries simply, returns bookmarkable results while preventing sensitive information leaks, and remains RESTful. It evaluates 5 approaches: using GET with query parameters, GET with a query body, POST with a body, a non-standard method with a body, and exposing a query definition resource. The preferred approach exposes a query definition resource that allows addressing individual queries and results through PUT, GET, and DELETE requests.

1. RESTful Search API
(design question)
philippe @marsteau

2. Goals
● Handle complex search queries
● Simple to use by developers
● Results can be bookmarked
● Do not leak PII / sensible information
● « RESTful »

3. Approaches
1. Use GET w/ specific query parameter(s)
(e.g. “q”, “search”)
● URI length limitation
● I18n URI considerations
● PII may leak in URIs (server logs, etc)
2. Use GET w/ query as body
● GET body has no semantic meaning to the request
● Non cacheable results
● Non addressable results

4. Approaches (cont’d)
3. Use POST w/ body
● Incorrectly implies state change
● Non cacheable results
● No automatic retry on network failures
● Non addressable results
4. Use non-standard HTTP method w/ body
● WebDAV query protocol uses SEARCH (RFC5323) back in 2008
● Unknown thus treated as unsafe method
● Non cacheable results
● Non addressable results

5. Approaches (cont’d)
5. Expose a Query Definition resource
● Query has own lifecycle (e.g. PUT /query-defs/123 + query def as body)
● Addressable query (e.g. GET /query-defs/123)
● Addressable results (e.g. GET /query-defs/123/results)
● Introduces state (e.g. DELETE /query-defs/123)
● Unintuitive to some developers (PUT query + GET results + DELETE query)