django/django

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

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

Django comes with an optional redirects application. It lets you store
redirects in a database and handles the redirecting for you. It uses the HTTP
response status code ``301 Moved Permanently`` by default.

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

To install the redirects app, follow these steps:

#. Ensure that the ``django.contrib.sites`` framework
   :ref:`is installed <enabling-the-sites-framework>`.
#. Add ``'django.contrib.redirects'`` to your :setting:`INSTALLED_APPS` setting.
#. Add ``'django.contrib.redirects.middleware.RedirectFallbackMiddleware'``
   to your :setting:`MIDDLEWARE` setting.
#. Run the command :djadmin:`manage.py migrate <migrate>`.

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

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

The :class:`~django.contrib.redirects.middleware.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`` using a 301 ("Moved Permanently") redirect. You can subclass
  :class:`~django.contrib.redirects.middleware.RedirectFallbackMiddleware`
  and set
  :attr:`~django.contrib.redirects.middleware.RedirectFallbackMiddleware.response_redirect_class`
  to :class:`django.http.HttpResponseRedirect` to use a
  ``302 Moved Temporarily`` redirect instead.
* 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` matters. Generally, you can put
:class:`~django.contrib.redirects.middleware.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 :source:`django/contrib/redirects/models.py`. You can access
    redirect objects via the :doc:`Django database API </topics/db/queries>`.
    For example:

    .. code-block:: pycon

        >>> from django.conf import settings
        >>> from django.contrib.redirects.models import Redirect
        >>> # Add a new redirect.
        >>> redirect = Redirect.objects.create(
        ...     site_id=1,
        ...     old_path="/contact-us/",
        ...     new_path="/contact/",
        ... )
        >>> # Change a redirect.
        >>> redirect.new_path = "/contact-details/"
        >>> redirect.save()
        >>> redirect
        <Redirect: /contact-us/ ---> /contact-details/>
        >>> # Delete a redirect.
        >>> Redirect.objects.filter(site_id=1, old_path="/contact-us/").delete()
        (1, {'redirects.Redirect': 1})

Middleware
==========

.. class:: middleware.RedirectFallbackMiddleware

    You can change the :class:`~django.http.HttpResponse` classes used
    by the middleware by creating a subclass of
    :class:`~django.contrib.redirects.middleware.RedirectFallbackMiddleware`
    and overriding ``response_gone_class`` and/or ``response_redirect_class``.

    .. attribute:: response_gone_class

        The :class:`~django.http.HttpResponse` class used when a
        :class:`~django.contrib.redirects.models.Redirect` is not found for the
        requested path or has a blank ``new_path`` value.

        Defaults to :class:`~django.http.HttpResponseGone`.

    .. attribute:: response_redirect_class

        The :class:`~django.http.HttpResponse` class that handles the redirect.

        Defaults to :class:`~django.http.HttpResponsePermanentRedirect`.