Debugging for RESTful HTTP Services

The X-Debug Request Header

Clients wishing to be sent debugging messages should send a list of tokens representing the classes of messages they are interested in.

An example client request:

GET / HTTP/1.1
Host: webapp.example.com
X-Debug: auth, db, conneg

Each class of message is indicated by a case-insensitive token. Multiple X-Debug tokens may be specified. Valid tokens are specified in Debugging Tokens. Additional application-specific tokens may also be requested — these must begin with x-.

As a special case, a header of X-Debug: * indicates that the client is interested in all debugging messages.

Debugging Tokens

auth

Indicates that the client is interested in debugging messages concerned with authentication and authorisation.

conneg

Indicates that the client is interested in debugging messages concerned with connection negotiation. This includes automatically negotiated media types, languages, character sets and so forth.

db

Indicates that the client is interested in debugging messages concerned with database access. This may include database query explanations, access problems and so forth.

logic

Indicates that the client is interested in application-specific logic debugging messages. For example, indications that the server has reached a supposedly impossible state.

Responses

Applications may provide three levels of debugging information:

errors

Problems of such a severity that it is impossible for a representation of the requested resource to be delivered.

warnings

Problems that may result in the delivery of a sub-optimal representation of the requested resource.

notices

Additional information that may be useful for people developing clients that interact with the requested resource.

Classification of a debugging message as one of these levels is left up to the server. Debugging messages are communicated to the client using different techniques depending on the level of message.

Error Responses

This specification defers to [RFC2616]. If a server reaches a condition that will generate an error-level message, the server must respond with an appropriate 4xx or 5xx status code and a description of the error in the HTTP message body.

Servers may inspect the X-Debug request header to tailor the message body to the interests of the client.

Warning Responses

Servers should include a Warning header for each warning message that the client is known to be interested in, and may include Warning headers for other warning-level messages. The syntax of the Warning header is defined in [RFC2616].

Servers should indicate the class of warning (e.g. conneg or auth) in square brackets at the start of the warn-text section of the header. For example:

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Warning: 199  "[conneg] The plain text representation of this resource is
  significantly less pretty than the HTML version."

Notice Responses

Notices are represented by HTTP response headers of the pattern X-Debug-class where "class" is the class of notice. For example:

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
X-Debug-CONNEG: Automatically generating HTML from XML input.

Servers should include these messages when the client has indicated it is interested via the X-Debug request header. Servers should not include these headers in responses to disinterested clients, as it is a waste of bandwidth. (Even with gzipped responses, the HTTP header is transmitted uncompressed.)

Security Considerations

Developers should be aware that exposing the internals of an application's processing and structure may pose security risks. They may wish to expose debugging messages only to authenticated clients or a restricted set of IP addresses.

Appendix A: References

RFC2616

Hypertext Transfer Protocol — HTTP/1.1, Roy T Fielding et al. RFC 2616. <http://www.ietf.org/rfc/rfc2616.txt>.

---