Semantic Web

Debugging for RESTful HTTP Services

Buzzword.org.uk Draft 29 September 2009

This version:
http://buzzword.org.uk/2009/rest-debug/spec-20090929
Latest version:
http://buzzword.org.uk/2009/rest-debug/spec
Editor:
Toby Inkster

Abstract

This document specifies a technique for HTTP servers to offer debugging information (warnings, notices) to clients; and a method for HTTP clients to advertise the fact that they would like this information.

A possible use-case would be a development tool that showed a browser side-panel with debugging messages while using a web service.

Status of this Document

This document is published by buzzword.org.uk, a web site that hosts various specifications, articles and tools of use to web publishers. This is not a W3C recommendation. It is not even a buzzword.org.uk recommendation yet.

The author welcomes feedback on this draft by e-mail to [email protected].

Licence

This document is available under a licence which allows the creation of derivative works under certain conditions. For the purpose of licensing, implementations of the ideas considered in this specification shall not be considered derivative works.

Table of Contents

  1. 1 The X-Debug Request Header
    1. 1.1 Debugging Tokens
      1. 1.1.1 auth
      2. 1.1.2 conneg
      3. 1.1.3 db
      4. 1.1.4 logic
  2. 2 Responses
    1. 2.1 Error Responses
    2. 2.2 Warning Responses
    3. 2.3 Notice Responses
  3. 3 Security Considerations
  4. Appendix A: References

1 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.

1.1 Debugging Tokens

1.1.1 auth

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

1.1.2 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.

1.1.3 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.

1.1.4 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.

2 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.

2.1 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.

2.2 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."

2.3 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.)

3 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>.