=================
The redirects app
=================

.. module:: django.contrib.redirects
   :synopsis: A framework for managing redirects.

Django comes with an optional redirects application. It lets you store simple
redirects in a database and handles the redirecting for you.

Installation
============

To install the redirects app, follow these steps:

1. Ensure that the ``django.contrib.sites`` framework
   :ref:`is installed <enabling-the-sites-framework>`.
2. Add ``'django.contrib.redirects'`` to your :setting:`INSTALLED_APPS` setting.
3. Add ``'django.contrib.redirects.middleware.RedirectFallbackMiddleware'``
   to your :setting:`MIDDLEWARE_CLASSES` setting.
4. Run the command :djadmin:`manage.py syncdb <syncdb>`.

How it works
============

``manage.py syncdb`` creates a ``django_redirect`` table in your database. This
is a simple lookup table with ``site_id``, ``old_path`` and ``new_path`` fields.

The ``RedirectFallbackMiddleware`` does all of the work. Each time any Django
application raises a 404 error, this middleware checks the redirects database
for the requested URL as a last resort. Specifically, it checks for a redirect
with the given ``old_path`` with a site ID that corresponds to the
:setting:`SITE_ID` setting.

* If it finds a match, and ``new_path`` is not empty, it redirects to
  ``new_path``.
* If it finds a match, and ``new_path`` is empty, it sends a 410 ("Gone")
  HTTP header and empty (content-less) response.
* If it doesn't find a match, the request continues to be processed as
  usual.

The middleware only gets activated for 404s -- not for 500s or responses of any
other status code.

Note that the order of :setting:`MIDDLEWARE_CLASSES` matters. Generally, you
can put ``RedirectFallbackMiddleware`` at the end of the list, because it's a
last resort.

For more on middleware, read the :doc:`middleware docs
</topics/http/middleware>`.

How to add, change and delete redirects
=======================================

Via the admin interface
-----------------------

If you've activated the automatic Django admin interface, you should see a
"Redirects" section on the admin index page. Edit redirects as you edit any
other object in the system.

Via the Python API
------------------

.. class:: models.Redirect

    Redirects are represented by a standard :doc:`Django model </topics/db/models>`,
    which lives in `django/contrib/redirects/models.py`_. You can access redirect
    objects via the :doc:`Django database API </topics/db/queries>`.

.. _django/contrib/redirects/models.py: https://github.com/django/django/blob/master/django/contrib/redirects/models.py