Django integration

HTTPolice has a package for integrating with Django 1.8+:

$ pip install Django-HTTPolice

This package provides django_httpolice.HTTPoliceMiddleware. Add it to your MIDDLEWARE_CLASSES, as close to the top as possible:

MIDDLEWARE_CLASSES = [
    'django_httpolice.HTTPoliceMiddleware',
    'django.middleware.common.CommonMiddleware',
    # ...
]

This middleware does nothing until you also set the HTTPOLICE_ENABLE setting to True.

When enabled, the middleware checks all exchanges passing through it. Then, there are two different ways to see the results of these checks.

Viewing the backlog

All exchanges checked by the middleware are stored in a global variable called the backlog. By default, it holds up to 20 latest exchanges, but you can override by setting HTTPOLICE_BACKLOG to a different number.

The package also provides the django_httpolice.report_view() function. Add it to your URLconf like this:

import django_httpolice

urlpatterns = [
    # ...
    url(r'^httpolice/$', django_httpolice.report_view),
    # ...
]

When you start the server and open /httpolice/ (or whatever URL you chose), you will see an HTML report on all the exchanges currently in the backlog. The latest exchanges are shown at the top of the report.

If HTTPOLICE_ENABLE is not True, the view responds with 404 (Not Found).

You can also access the backlog from your own code: it’s in the django_httpolice.backlog variable, as a sequence of httpolice.Exchange objects.

Raising on errors

If you set the HTTPOLICE_RAISE setting to True, then the middleware will raise a django_httpolice.ProtocolError whenever a response is found to have any errors (that are not silenced).

This can be used to fail tests on errors:

$ python manage.py test
.E.
======================================================================
ERROR: test_get_plain (example_app.test.ExampleTestCase)
----------------------------------------------------------------------
Traceback (most recent call last):
  [...]
  File "[...]/django_httpolice/middleware.py", line 81, in process_response
    raise ProtocolError(exchange)
django_httpolice.common.ProtocolError: HTTPolice found errors in this response:
------------ request 1 : GET /api/v1/?name=Martha&format=plain
C 1070 No User-Agent header
------------ response 1 : 200 OK
E 1038 Bad JSON body


----------------------------------------------------------------------
Ran 3 tests in 0.351s

FAILED (errors=1)

The exchange is still added to the backlog.

Silencing unwanted notices

To silence notices you don’t care about, you can use the HTTPOLICE_SILENCE setting:

HTTPOLICE_SILENCE = [1070, 1110, 1194]

They will disappear from reports and will not cause ProtocolError.

By default, HTTPOLICE_SILENCE includes some notices that are irrelevant because of Django specifics, such as 1110.

Of course, the HTTPolice-Silence header works, too:

def test_unauthorized(self):
    response = self.client.get('/api/v1/products/',
                               HTTP_HTTPOLICE_SILENCE='1194 resp')
    self.assertEqual(response.status_code, 401)