What belongs in an HTTP request header vs the request body?

Question

I'm working on a set of web services for a mobile client, and the requirements call for a unique device id to be included with all requests, to be stored in certain requests, and used to filter results in others.

A suggestion was made that it be put in a custom HTTP header since it will be included with all requests, so I began to wonder what criteria might be used to determine if a given piece of data belongs in a header or along with other data in the request body.

Is there any such criteria?

Answer 1

When the information is important, you should put it into the body.

Why?

1. proxy servers are allowed to modify headers. Many are configured to strip any headers they don't know. This, however, only applies when you use unencrypted HTTP. When you use HTTPS, the proxy can't change the headers because they are encrypted.
2. When you use a webservice, you usually do so for interoperability with other devices, services and tools. Most APIs and tools which work with webservices can easily change requests, but many make it difficult or even impossible to add custom headers. This, of course, only applies when interoperability is a concern. But when you don't care, you might want to ask yourself why you are using webservices in the first place instead of just building your own protocol on raw TCP.

Answer 2

While the line is somewhat blurry, for me a rule of thumb is: data that your business logic works on should be in the body, metadata can/should be put in headers.

Another way of looking at it is: data which appears only in specific kinds of requests should be in the body while data which is handled consistently across the whole application should go into headers.

Yet another point of view is: can you imagine that a piece of data is handled globally, e.g. by a router/firewall rather than by your application? If yes, it should probably go in the headers rather than in the body.

Some examples of applying these rules would be:

• Security credentials go into headers since most probably they will be handled the same in all places of an application; at implementation level there will probably be some request filter rejecting requests without valid credentials regardless of the actual endpoint handling the request in case it does get through the filter.
• If, on the other hand, you have an endpoint which allows an admin to add users to your system, the login of the user to be created should be in request body since: a) it is handled by your application's business logic, b) it appears in this particular endpoint but not in others.
• Options which control caching may well fit into headers (unless caching is a core part of your application's business logic).

Going back to your question about the unique device ID: if it is used in a consistent way everywhere, e.g. only for logging, it can be put in the headers. But if it is used to filter requests in different ways depending on the endpoint, it would better be in the body. Of course if you have both use cases, it is probably better to stick with just a single way of passing it (probably the headers) rather than forcing the API user to put the same data in two places, giving you the dilemma of either allowing inconsistent inputs or implementing some kind of validation.

Answer 3

I think that headers should either have metadata(like version, content-type, content-length, cache data details with max time limit, etc details) or can also have data which is applicable to the entire application(like the details of the user who logged-in into the application, user role, etc)

Secondly, in big enterprises there could also be scenarios where the rest template is not created within the application code. The rest template could actually be present in a library/dependency(provided by some other team and is used by your team). In that case if we want to print the request and response details then it is not possible because we cannot add interceptor to the rest template of the library/dependency (This is not the case for Soap messages where it is easy to log the soap request and response even if the SOAP messages are created by a library/dependency and not directly within the application code). So this is one more reason why the data should be present in URI or the body so that we can easily see what is in the data object

Answer 4

The content of the client request; which will not be changed across multiple requests to the same server will be part of HEADER e.g. credentials, others which are frequently changes per request will be part of BODY.

OR

property of the message/body content will go into header. e.g) encoding type, content-length, content-type.

AND

In your case like filter parameters should be added as query/request params in the url.

/mobiles?type=MOTO&colour=black

In restful services the url itself will refer to an object

/conferences/{conference_id} --> refers specific conference