HTTP REST API: Is it wrong to put search parameters in a custom header?

Question

The contents of search string are typically sent as part of the URI query:

https://domain.name/resource?search=something+i+am+searching+for

Those same contents can be sent as the value of a custom HTTP header:

$ curl -v "https://google.com" -H "custom-search-header: something i am searching for"
> GET / HTTP/2
> Host: google.com
> user-agent: curl/7.87.0
> accept: */*
> custom-search-header: something i am searching for

Question: Is it wrong to put the search string in a custom header?

Would the answer change if the API is a "backend" service versus a "frontend" service?

• Jon Raynor: Can you add why you don't want to use the GET/Query String Parameter?
• Greg Burghardt: Can you give a more concrete example of this customer search header name and value?
• SunSparc: @JonRaynor, for this question, I do not consider relevant the reasoning behind not wanting to use the GET/Query String Parameter. I am simply looking for a definitive best practice on the subject.
• DavidT: The main issue with using custom headers is that caches may not be aware of them - hence return a "stale" result that only differs from the intended result by because of the headers.
• Laiv: You might be interested in this. In a nutshell, what you suggest is known as header fields. They aren't wrong per se, but you might find some limitations not strictly related to HTTP semantics, but with HTTP clients' implementations, elements of the network topology, etc

Answer 1

One of the main ideas behind REST is that each resource should be identifiable by a unique URL, and requesting a resource should be as simple as requesting this URL.

When you transfer search parameters as HTTP query parameters, they are present in the URL and this corresponds to the REST idea. When you put search parameters to headers, the URL does not contains them, which contradicts to the REST idea.

Using headers for search parameters does not say if the approach is good or not in particular case. But if you want to follow namely REST style, then using headers for search parameters should be avoided.

Answer 2

Question: Is it wrong to put the search string in a custom header?

How our you communicating to a general purpose client implementation that it should copy information into a bespoke header that only your specific implementation understands?

I'd suggest that you review REST APIs must be hypertext driven (Fielding 2008), with this question in mind.

Putting information into bespoke headers, like putting information into the request body, effectively hides it from the transfer-of-documents-over-a-network application.

To do so isn't necessarily capital-W Wrong, but there are tradeoffs that you should evaluate in your context.

Answer 3

Typically, the items in the HTTP header are for every request and are processed by the server prior to API endpoint processing. In this example, this would be GET only. Typically an API would have other endpoints such as POST, PATCH, and DELETE. In those cases, the search header custom field would have no value, so sending it would not be necessary.

Therefore, I would not advocate putting search parameters into the header as a best practice as not all requests will need that information. The header information should contain information for any request.