Clever Geek Handbook

Search verb in HTTP API

What's the best way to search the API?

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


source to share


3 answers


Don't include a body with a GET request. This is against the spec :

The payload in the GET request message has no specific semantics; sending a payload body on a GET request may result in the request being rejected.

There are trade-offs between the other two options. GET requests are cacheable, secure, and idempotent. They are also limited in size.



POST requests are not reliably cached, secure or idempotent, and have no size limit. There's also more flexibility, you can later create a server side filter resource in addition to returning a search result, and then the search can use that filter, perhaps with a GET, although be careful if you allow caching and changes to the filter definition after it creation.

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

+3


source


POST requests are considered modified or generated on the server. GET is considered a "safe method" that does not affect the server database.



Since search queries usually don't change any data, you should use a GET request. The limit is at least 2000 characters (IE), so you are fairly safe most of the time.

0


source


Definitely accomplish 1 GET

using query parameters. Most likely it will be cached.

If nothing in the data model changes on the server, your request should be GET. Server operations like logging are fine, but filter creation (as suggested in the other answer), unlike query cache, for example, is not.

0


source






More articles:


All Articles