Using Custom Headers for Response Messages; Bad Practice?

Question

I am working on a REST API using Java and the Spring Framework. Currently, I return a message from the server in a custom HTTP header called Server-Response. This is used in both cases where errors occur and successful requests are completed. Is using a custom HTTP header for this purpose a bad practice?

Why did I do this?

Cases exist where I need the body for an object but require an additional string response.
Java is strictly typed; if I return a List<Object>, then I cannot return an additional string.
Messages from the server must be more specific than what is provided by a global exception handler.

Why not to do this?

Spring provides a @ExceptionHandler annotation to allow exceptions to be handled differently, allowing for a String response.
Maybe headers should not contain important information such as error messages.

Sample GET Request

I can get a list of locations from the following example URL: https://fakeurl.com/api/locations

Request Headers

Accept:text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,/;q=0.8
Accept-Encoding:gzip, deflate, sdch Accept-Language:en-US,en;q=0.8
Cache-Control:no-cache Connection:keep-alive
Upgrade-Insecure-Requests:1
User-Agent:Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/50.0.2661.94 Safari/537.36
Status Code:200 OK

Response Headers

Content-Type:application/json;charset=UTF-8
Date:Wed, 11 May 2016 15:41:03 GMT
Expires:Wed, 31 Dec 1969 19:00:00 EST Expires:-1
Server:Apache-Coyote/1.1
Server Response:Successfully retrieved all locations!
Transfer-Encoding:chunked
X-Powered-By:Servlet 2.5; JBoss-5.0/JBossWeb-2.1

Response Body

[
    {"locId":1,"descr":"New York","activeStatus":"ACTIVE"},
    {"locId":2,"descr":"Los Angelas","activeStatus":"ACTIVE"},
    {"locId":3,"descr":"Canada","activeStatus":"ACTIVE"},
    {"locId":4,"descr":"Mexico","activeStatus":"ACTIVE"},
    {"locId":5,"descr":"Nebraska","activeStatus":"ACTIVE"},
    {"locId":6,"descr":"Texas","activeStatus":"ACTIVE"},
    {"locId":7,"descr":"Michigan","activeStatus":"ACTIVE"}
]

There is no definite answer but the header is not intended to be the response. It's meta data. You can always return a custom Response object that contains all the fileds you like, it can act like a container for everything like stackoverflow.com/questions/12806386/… — zapl
Thanks; that is exactly what I was looking for. I wish I had known this a year ago. — William Callahan

Serge Ballesta Serge Ballesta · Accepted Answer · 2016-05-11T16:13:19

TL/DR: it depends on your actual usage.

It really depends on how you process the information that you pass in a custom header. It makes sense to use a custom header if you want to pass information at an enveloppe level. I mean, this information has nothing to do with the data that you want to retrieve, and as such should not be stored there, but is used by an encapsulating tool. A real world example would be a data server that could be accessed through different protocols, say HTTP and for example mail (replies with another mail) and a dedicated protocol. In that case the information on why or how the actual server could not be reached should be passed at an enveloppe level and a custom response header would be particurlarly adapted.

Another example would be when you use the same tool to access different information types. The payload should only contain the actual information, that would be transparently passed to a caller, and the error conditions could be passed in a response headers and would be processed by the exchange tool.

The only rule you should obey is that a custom header should begin by X-.

Using Custom Headers for Response Messages; Bad Practice?

1 Answers