Search verb in HTTP API

Question

What is best practice for search in API?

• GET + query parameters, example: GET /search?q=phone
• GET + parameters in body, example: GET /search {"query": "phone"}
• POST + parameters in body, example: POST /search {"query": "phone"}

Answer 1

Don't include a body with a GET request. That's against the spec:

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.

There are tradeoffs between the other two options. GET requests are cacheable, safe, and idempotent. They're also limited in size.

POST requests are not reliably cacheable, safe, or idempotent, and have no size limit. There's also more flexibility baked in - you can later create a filter resource on the server side in addition to returning the search result, and later searches can use that filter, possibly with a GET, although be careful if you allow caching and changes to the filter definition after it's created.

Looking at your specific example, supporting a single "search" endpoint can get messy pretty fast. If you haven't already, I would encourage you to consider other options.