django-simple-api-proxy 2.0.0__tar.gz → 2.0.1__tar.gz

{django_simple_api_proxy-2.0.0/src/django_simple_api_proxy.egg-info → django_simple_api_proxy-2.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-simple-api-proxy
-Version: 2.0.0
+Version: 2.0.1
 Summary: Easy to proxy any APIs you want.
 Home-page: https://github.com/NatLee/django-simple-api-proxy
 Author: Nat Lee
@@ -448,19 +448,19 @@ These are why pass-through became the default; JSON mode keeps them for compatib
 The proxy logs through loguru: every request at `DEBUG` level, failures at `ERROR` level with the reason and the traceback. Request bodies are logged by size or field name only, never by value, and headers by name only. The `PUT` from [What goes through](#what-goes-through) logs this:
 
 ```log
-2026-11-03 15:19:50.689 | DEBUG    | django_simple_api_proxy.views:_forward:322 - Proxy PUT /my_test_route/anything/items
-2026-11-03 15:19:50.689 | DEBUG    | django_simple_api_proxy.views:get_proxy_path:157 - Upstream URL: https://httpbin.org/anything/items
-2026-11-03 15:19:50.689 | DEBUG    | django_simple_api_proxy.views:_pass_through:365 - Forwarding headers ['Accept', 'Content-Type', 'User-Agent', 'X-Hello'] and 306 bytes of body
-2026-11-03 15:19:51.344 | DEBUG    | django_simple_api_proxy.views:_pass_through:375 - API server answered 200 (application/json, 557 bytes)
+2026-11-03 16:39:45.063 | DEBUG    | django_simple_api_proxy.pass_through:_forward:258 - Proxy PUT /my_test_route/anything/items
+2026-11-03 16:39:45.064 | DEBUG    | django_simple_api_proxy.pass_through:get_proxy_path:135 - Upstream URL: https://httpbin.org/anything/items
+2026-11-03 16:39:45.064 | DEBUG    | django_simple_api_proxy.pass_through:_forward:265 - Forwarding headers ['Accept', 'Content-Type', 'User-Agent', 'X-Hello'] and 306 bytes of body
+2026-11-03 16:39:45.714 | DEBUG    | django_simple_api_proxy.pass_through:_forward:275 - API server answered 200 (application/json, 557 bytes)
 ```
 
 and a `POST` of `{"user": "nat", "password": "hunter2"}` in JSON mode this:
 
 ```log
-2026-11-03 15:20:04.450 | DEBUG    | django_simple_api_proxy.views:_forward:322 - Proxy POST /my_test_route/
-2026-11-03 15:20:04.450 | DEBUG    | django_simple_api_proxy.views:preprocess_request_body:191 - JSON body fields: ['user', 'password']
-2026-11-03 15:20:04.450 | DEBUG    | django_simple_api_proxy.views:get_proxy_path:157 - Upstream URL: https://httpbin.org/anything
-2026-11-03 15:20:04.450 | DEBUG    | django_simple_api_proxy.views:update_payload:174 - Username: #anonymous
+2026-11-03 16:40:00.380 | DEBUG    | django_simple_api_proxy.json_mode:_forward:171 - Proxy POST /my_test_route/
+2026-11-03 16:40:00.383 | DEBUG    | django_simple_api_proxy.json_mode:preprocess_request_body:101 - JSON body fields: ['user', 'password']
+2026-11-03 16:40:00.383 | DEBUG    | django_simple_api_proxy.json_mode:get_proxy_path:146 - Upstream URL: https://httpbin.org/anything
+2026-11-03 16:40:00.383 | DEBUG    | django_simple_api_proxy.json_mode:update_payload:84 - Username: #anonymous
 ```
 
 Unless you configure it, loguru prints all of this to stderr. Its default handler also prints the values of local variables in tracebacks (`diagnose=True`), so when a request fails, its body can still show up in the traceback. If bodies may hold passwords or tokens, turn the proxy's log off, or keep only `INFO` and up without the variable values:

{django_simple_api_proxy-2.0.0 → django_simple_api_proxy-2.0.1}/README.md

@@ -388,19 +388,19 @@ These are why pass-through became the default; JSON mode keeps them for compatib
 The proxy logs through loguru: every request at `DEBUG` level, failures at `ERROR` level with the reason and the traceback. Request bodies are logged by size or field name only, never by value, and headers by name only. The `PUT` from [What goes through](#what-goes-through) logs this:
 
 ```log
-2026-11-03 15:19:50.689 | DEBUG    | django_simple_api_proxy.views:_forward:322 - Proxy PUT /my_test_route/anything/items
-2026-11-03 15:19:50.689 | DEBUG    | django_simple_api_proxy.views:get_proxy_path:157 - Upstream URL: https://httpbin.org/anything/items
-2026-11-03 15:19:50.689 | DEBUG    | django_simple_api_proxy.views:_pass_through:365 - Forwarding headers ['Accept', 'Content-Type', 'User-Agent', 'X-Hello'] and 306 bytes of body
-2026-11-03 15:19:51.344 | DEBUG    | django_simple_api_proxy.views:_pass_through:375 - API server answered 200 (application/json, 557 bytes)
+2026-11-03 16:39:45.063 | DEBUG    | django_simple_api_proxy.pass_through:_forward:258 - Proxy PUT /my_test_route/anything/items
+2026-11-03 16:39:45.064 | DEBUG    | django_simple_api_proxy.pass_through:get_proxy_path:135 - Upstream URL: https://httpbin.org/anything/items
+2026-11-03 16:39:45.064 | DEBUG    | django_simple_api_proxy.pass_through:_forward:265 - Forwarding headers ['Accept', 'Content-Type', 'User-Agent', 'X-Hello'] and 306 bytes of body
+2026-11-03 16:39:45.714 | DEBUG    | django_simple_api_proxy.pass_through:_forward:275 - API server answered 200 (application/json, 557 bytes)
 ```
 
 and a `POST` of `{"user": "nat", "password": "hunter2"}` in JSON mode this:
 
 ```log
-2026-11-03 15:20:04.450 | DEBUG    | django_simple_api_proxy.views:_forward:322 - Proxy POST /my_test_route/
-2026-11-03 15:20:04.450 | DEBUG    | django_simple_api_proxy.views:preprocess_request_body:191 - JSON body fields: ['user', 'password']
-2026-11-03 15:20:04.450 | DEBUG    | django_simple_api_proxy.views:get_proxy_path:157 - Upstream URL: https://httpbin.org/anything
-2026-11-03 15:20:04.450 | DEBUG    | django_simple_api_proxy.views:update_payload:174 - Username: #anonymous
+2026-11-03 16:40:00.380 | DEBUG    | django_simple_api_proxy.json_mode:_forward:171 - Proxy POST /my_test_route/
+2026-11-03 16:40:00.383 | DEBUG    | django_simple_api_proxy.json_mode:preprocess_request_body:101 - JSON body fields: ['user', 'password']
+2026-11-03 16:40:00.383 | DEBUG    | django_simple_api_proxy.json_mode:get_proxy_path:146 - Upstream URL: https://httpbin.org/anything
+2026-11-03 16:40:00.383 | DEBUG    | django_simple_api_proxy.json_mode:update_payload:84 - Username: #anonymous
 ```
 
 Unless you configure it, loguru prints all of this to stderr. Its default handler also prints the values of local variables in tracebacks (`diagnose=True`), so when a request fails, its body can still show up in the traceback. If bodies may hold passwords or tokens, turn the proxy's log off, or keep only `INFO` and up without the variable values:

django_simple_api_proxy-2.0.1/src/django_simple_api_proxy/__init__.py

@@ -0,0 +1 @@
+__version__ = '2.0.1'

{django_simple_api_proxy-2.0.0 → django_simple_api_proxy-2.0.1}/src/django_simple_api_proxy/checks.py

@@ -20,6 +20,9 @@ from django_simple_api_proxy.conf import pass_through_enabled
 
 _ID = "django_simple_api_proxy."
 
+#: The schemes requests can send to.
+URL_SCHEMES = ("http://", "https://")
+
 
 def check_settings(app_configs: Any = None, **kwargs: Any) -> list[checks.CheckMessage]:
     """Warn about proxy settings that send requests to the wrong place."""
@@ -30,7 +33,7 @@ def check_settings(app_configs: Any = None, **kwargs: Any) -> list[checks.CheckM
     # Pass-through mode trims the slashes itself, so only the scheme matters there.
     exact_paths = not pass_through_enabled()
 
-    if isinstance(url, str) and not url.startswith(("http://", "https://")):
+    if isinstance(url, str) and not url.startswith(URL_SCHEMES):
         warnings.append(checks.Warning(
             "TARGET_API_URL does not start with http:// or https://, "
             "so no request can reach it.",
@@ -63,10 +66,6 @@ def check_settings(app_configs: Any = None, **kwargs: Any) -> list[checks.CheckM
     return warnings
 
 
-#: Methods only JSON mode calls; in pass-through mode an override of one does nothing.
-JSON_MODE_HOOKS = ("update_payload", "preprocess_request_body", "response")
-
-
 def _subclasses(cls: Any) -> Iterator[Any]:  # APIProxy, imported late (it needs the settings)
     for sub in cls.__subclasses__():
         yield sub
@@ -76,6 +75,7 @@ def _subclasses(cls: Any) -> Iterator[Any]:  # APIProxy, imported late (it needs
 def check_json_mode_hooks(app_configs: Any = None, **kwargs: Any) -> list[checks.CheckMessage]:
     """Warn about subclasses that override JSON-mode methods but run in pass-through mode."""
     try:
+        from django_simple_api_proxy.json_mode import JSON_MODE_HOOKS
         from django_simple_api_proxy.views import APIProxy
     except ImproperlyConfigured:
         return []  # a setting is missing, and Django reports that already

{django_simple_api_proxy-2.0.0 → django_simple_api_proxy-2.0.1}/src/django_simple_api_proxy/headers.py

@@ -19,6 +19,11 @@ HOP_BY_HOP_HEADERS = frozenset({
 #: already answered ``Expect: 100-continue``.
 NOT_FORWARDED_REQUEST_HEADERS = frozenset({"host", "content-length", "accept-encoding", "expect"})
 
+#: The Content-Type that Django's runserver (Python's wsgiref) fills in for requests
+#: that have none. On a request without a body it came from the development server,
+#: not from the client, so it stays behind.
+RUNSERVER_DEFAULT_CONTENT_TYPE = "text/plain"
+
 #: Response headers that no longer fit once requests has read and decoded the reply,
 #: or that your web server sets itself (nginx hides ``Date`` and ``Server`` too).
 #: ``Set-Cookie`` goes through separately, one cookie at a time.
@@ -44,14 +49,14 @@ def _without(headers: Mapping[str, str], names: Iterable[str]) -> dict[str, str]
 def request_headers_to_forward(headers: Mapping[str, str], has_body: bool) -> dict[str, str]:
     """The client's headers that go on to the API server.
 
-    Without a body, ``Content-Type: text/plain`` is dropped: ``runserver`` adds it to
-    requests that have no body and no ``Content-Type``.
+    Without a body, the Content-Type runserver makes up (RUNSERVER_DEFAULT_CONTENT_TYPE)
+    stays behind.
     """
     forwarded = _without(headers, NOT_FORWARDED_REQUEST_HEADERS)
     if not has_body:
         forwarded = {
             name: value for name, value in forwarded.items()
-            if not (name.lower() == "content-type" and value == "text/plain")
+            if not (name.lower() == "content-type" and value == RUNSERVER_DEFAULT_CONTENT_TYPE)
         }
     return forwarded
 

django_simple_api_proxy-2.0.1/src/django_simple_api_proxy/json_mode.py

@@ -0,0 +1,202 @@
+"""JSON mode: the proxy as it worked in 1.x, kept as a compatibility layer.
+
+Why it is kept: 2.0 made pass-through mode the default, which changes what clients
+get (the API server's status codes, any content type, no ``username``). With
+``PROXY_PASS_THROUGH = False``, or ``pass_through = False`` on a subclass, a project
+upgrades and keeps the 1.x answers until it is ready to switch.
+
+How it fits in: ``JSONMode`` sits on top of ``PassThroughView``. In the few steps
+where the two modes differ it checks ``pass_through`` and either does what 1.x did
+or hands the step down to pass-through mode, which knows nothing about this module.
+``APIProxy`` (views.py) is ``JSONMode`` under its public name.
+
+When it can go: in a major release, once projects no longer set
+``PROXY_PASS_THROUGH = False``. Removing it means deleting this module, the JSON-mode
+checks in checks.py (W002-W005) and the 1.x tests in tests/test_api_proxy.py, and
+basing ``APIProxy`` on ``PassThroughView``.
+"""
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+from urllib.parse import urlparse
+
+import requests
+from django.http import HttpResponse, JsonResponse
+from loguru import logger
+from rest_framework.request import Request
+
+from django_simple_api_proxy import conf
+from django_simple_api_proxy.pass_through import (
+    ERROR_REPLY,
+    ERROR_REPLY_TEXT,
+    PassThroughView,
+    _content_type,
+    _failure_reason,
+)
+
+#: Sent as ``username`` when the request has no authenticated user.
+ANONYMOUS_USERNAME = "#anonymous"
+
+#: The methods only JSON mode calls. A subclass in pass-through mode that overrides
+#: one of them gets warning W005, because the override does nothing there.
+JSON_MODE_HOOKS = ("update_payload", "preprocess_request_body", "response")
+
+_JSON_TYPE_NAMES = {list: "an array", str: "a string", int: "a number", float: "a number",
+                    bool: "true or false", type(None): "null"}
+
+
+class ProxyError(ValueError):
+    """A request JSON mode cannot forward; the message says why, for the log."""
+
+
+def _field_names(body: Any) -> str:
+    """Describe a decoded JSON body for the log without any of its values."""
+    if isinstance(body, dict):
+        return str(list(body))
+    return "(not a JSON object)"
+
+
+class JSONMode(PassThroughView):
+    """JSON in, JSON out, as in 1.x, when ``pass_through`` is off."""
+
+    #: True (the default since 2.0) passes everything through; False brings back
+    #: the JSON mode of 1.x.
+    pass_through: bool = conf.pass_through_enabled()
+
+    # -- Hooks only JSON mode calls (JSON_MODE_HOOKS) --------------------------
+
+    def update_payload(self, request: Request, params: Any) -> dict[str, Any]:
+        """Set ``username`` in ``params`` and return ``params``.
+
+        The value is the name of the user Django REST framework authenticated, or
+        ``#anonymous``. A ``username`` sent by the client is replaced.
+        """
+        if not isinstance(params, dict):
+            kind = _JSON_TYPE_NAMES.get(type(params), type(params).__name__)
+            raise ProxyError(f"the JSON body must be an object ({{...}}), not {kind}")
+        user = request.user
+        username = getattr(user, "username", None)
+        if username is None and hasattr(user, "get_username"):
+            username = user.get_username()  # a custom user model without `username`
+        username = username or ANONYMOUS_USERNAME
+        logger.debug("Username: {}", username)
+        params.update({"username": username})
+        return params
+
+    def preprocess_request_body(self, request: Request) -> tuple[str, dict[str, Any]]:
+        """Return the API server URL and the JSON body to send for ``request``.
+
+        An empty body counts as ``{}``; ``username`` is added by ``update_payload``.
+        """
+        try:
+            params = json.loads(request.body) if request.body else {}
+        except ValueError as exc:
+            raise ProxyError(
+                f"the request body is not JSON (Content-Type: {request.content_type or 'none'}); "
+                "JSON mode only forwards JSON, set PROXY_PASS_THROUGH = True to forward any body"
+            ) from exc
+        # Field names only: the values may be passwords or tokens.
+        logger.debug("JSON body fields: {}", _field_names(params))
+        path = self.get_proxy_path(request)
+        params = self.update_payload(request, params)
+        return path, params
+
+    # Django REST framework stores the finished reply in `self.response` after the
+    # handler returns, which only hides this method once it is no longer needed.
+    def response(self, resp: Any) -> JsonResponse:  # type: ignore[override]
+        """Build the reply for the client from the API server's decoded JSON."""
+        return JsonResponse(resp, safe=False, json_dumps_params={"ensure_ascii": False})
+
+    # -- Steps where the modes differ ------------------------------------------
+    # Each one does what 1.x did when pass_through is off and hands the step to
+    # pass-through mode otherwise. super(PassThroughView, self) is Django REST
+    # framework's own behaviour, which 1.x used for these steps.
+
+    def head(self, request: Request, *args: Any, **kwargs: Any) -> HttpResponse:
+        """JSON mode answers HEAD like GET, as Django does."""
+        if self.pass_through:
+            return super().head(request, *args, **kwargs)
+        return self.get(request, *args, **kwargs)
+
+    def options(  # type: ignore[override]
+        self, request: Request, *args: Any, **kwargs: Any
+    ) -> HttpResponse:
+        """JSON mode lets Django REST framework answer OPTIONS."""
+        if self.pass_through:
+            return super().options(request, *args, **kwargs)
+        return super(PassThroughView, self).options(request, *args, **kwargs)
+
+    def parse_path(self, request: Request) -> str:
+        """JSON mode: the first match of ``proxy_route_path`` (a regular expression) is
+        replaced with ``proxy_target_path`` and a trailing slash is dropped, so
+        ``/my_test_route/items/7/`` becomes ``/get/items/7``.
+        """
+        if self.pass_through:
+            return super().parse_path(request)
+        path = urlparse(request.get_full_path()).path.rstrip("/")
+        return re.sub(self.proxy_route_path, self.proxy_target_path, path, count=1)
+
+    def get_proxy_path(self, request: Request) -> str:
+        """JSON mode puts ``target_api_url`` and the path together as they are."""
+        if self.pass_through:
+            return super().get_proxy_path(request)
+        url = f"{self.target_api_url}{self.parse_path(request)}"
+        logger.debug("Upstream URL: {}", url)
+        return url
+
+    def perform_authentication(self, request: Request) -> None:
+        if self.pass_through:
+            return super().perform_authentication(request)
+        return super(PassThroughView, self).perform_authentication(request)
+
+    def perform_content_negotiation(self, request: Request, force: bool = False) -> Any:
+        if self.pass_through:
+            return super().perform_content_negotiation(request, force)
+        return super(PassThroughView, self).perform_content_negotiation(request, force)
+
+    def finalize_response(self, request: Request, response: Any, *args: Any, **kwargs: Any) -> Any:
+        if self.pass_through:
+            return super().finalize_response(request, response, *args, **kwargs)
+        return super(PassThroughView, self).finalize_response(request, response, *args, **kwargs)
+
+    def _forward(self, request: Request, method: str) -> HttpResponse:
+        """JSON mode: if anything fails on the way (a body that is not a JSON object,
+        an API server that cannot be reached, a reply that is not JSON), the error is
+        logged and the client gets ``{"status": "error"}`` with HTTP 200.
+        """
+        if self.pass_through:
+            return super()._forward(request, method)
+        logger.debug("Proxy {} {}", method, request.path)
+        try:
+            reply = self._json_from(self._send_upstream(request, method))
+        except Exception as exc:  # Whatever went wrong, the client gets the same answer.
+            reason = str(exc) if isinstance(exc, ProxyError) else _failure_reason(exc)
+            logger.exception("Could not proxy {} {}: {}. Replying {}",
+                             method, request.path, reason, ERROR_REPLY_TEXT)
+            reply = ERROR_REPLY.copy()
+        return self.response(reply)
+
+    # -- Internals ------------------------------------------------------------
+
+    def _send_upstream(self, request: Request, method: str) -> requests.Response:
+        """GET sends the query string on; the other methods send the JSON body on."""
+        if method == "GET":
+            params = dict(request.GET)
+            url = self.get_proxy_path(request)
+            params = self.update_payload(request, params)
+            return self.send_request(method, url, params=params)
+        url, body = self.preprocess_request_body(request)
+        return self.send_request(method, url, json=body)
+
+    @staticmethod
+    def _json_from(upstream: requests.Response) -> Any:
+        try:
+            return upstream.json()
+        except ValueError as exc:
+            raise ProxyError(
+                f"the API server answered HTTP {upstream.status_code} "
+                f"({_content_type(upstream)}), which is not JSON; "
+                "set PROXY_PASS_THROUGH = True to pass any reply on"
+            ) from exc

django_simple_api_proxy-2.0.1/src/django_simple_api_proxy/pass_through.py

@@ -0,0 +1,308 @@
+"""Pass-through mode: one route of your site passed through to another server.
+
+``PassThroughView`` sends a request for ``/<PROXY_ROUTE_PATH>/<rest>`` to
+``<TARGET_API_URL>/<PROXY_TARGET_PATH>/<rest>`` as the client sent it (method,
+path, query string, headers, body) and relays the reply as the server gave it
+(status, headers, cookies, body). Redirects go back to the client.
+
+This module knows nothing about the JSON mode of 1.x: ``APIProxy`` (views.py) is
+this view with the JSON mode (json_mode.py) layered on top.
+"""
+from __future__ import annotations
+
+import json
+import re
+from http import HTTPStatus
+from http.cookies import SimpleCookie
+from typing import Any, Mapping
+from urllib.parse import urljoin, urlsplit, urlunsplit
+
+import requests
+from django.conf import settings
+from django.http import Http404, HttpResponse, JsonResponse
+from django.utils.encoding import escape_uri_path
+from loguru import logger
+from rest_framework.request import Request
+from rest_framework.response import Response
+from rest_framework.views import APIView
+
+from django_simple_api_proxy import conf
+from django_simple_api_proxy.headers import (
+    request_headers_to_forward,
+    response_headers_to_relay,
+)
+
+conf.require_settings()
+
+#: What the client gets when a request cannot be proxied (both modes), and how the
+#: log quotes it.
+ERROR_REPLY = {"status": "error"}
+ERROR_REPLY_TEXT = json.dumps(ERROR_REPLY)
+
+#: Seconds the API server has to answer (requests' timeout); 1.x used the same.
+DEFAULT_TIMEOUT = 180
+
+#: What pass-through mode answers when the API server gives no answer: it did not
+#: answer in time, or it could not be reached at all.
+NO_ANSWER_IN_TIME = HTTPStatus.GATEWAY_TIMEOUT
+NO_ANSWER = HTTPStatus.BAD_GATEWAY
+
+
+def _failure_reason(exc: Exception) -> str:
+    """One line for the log about why the API server gave no answer."""
+    if isinstance(exc, requests.Timeout):
+        return "the API server did not answer in time"
+    if isinstance(exc, requests.ConnectionError):
+        return "could not connect to the API server"
+    if isinstance(exc, requests.RequestException):
+        return f"the request to the API server failed ({type(exc).__name__})"
+    return f"{type(exc).__name__}: {exc}"
+
+
+def _content_type(response: requests.Response) -> str:
+    return response.headers.get("Content-Type") or "no Content-Type"
+
+
+class RelayedResponse(HttpResponse):
+    """The API server's reply on its way to the client.
+
+    Like Django's own redirect responses it has ``url``, the ``Location`` it points
+    to, so Django's test client can follow a relayed redirect.
+    """
+
+    @property
+    def url(self) -> str | None:
+        return self.get("Location")
+
+
+class PassThroughView(APIView):
+    """Pass requests through to the API server and relay its replies as they are."""
+
+    # Anyone can use the stock proxy. Subclasses set these to require a login.
+    authentication_classes = []
+    permission_classes = []
+
+    # Read once, when this module is imported. Subclasses can set their own.
+    target_api_url: str = settings.TARGET_API_URL
+    proxy_route_path: str = settings.PROXY_ROUTE_PATH
+    proxy_target_path: str = settings.PROXY_TARGET_PATH
+
+    # -- HTTP methods: each one goes through as itself --------------------------
+
+    def get(self, request: Request, *args: Any, **kwargs: Any) -> HttpResponse:
+        return self._forward(request, "GET")
+
+    def post(self, request: Request, *args: Any, **kwargs: Any) -> HttpResponse:
+        return self._forward(request, "POST")
+
+    def put(self, request: Request, *args: Any, **kwargs: Any) -> HttpResponse:
+        return self._forward(request, "PUT")
+
+    def patch(self, request: Request, *args: Any, **kwargs: Any) -> HttpResponse:
+        return self._forward(request, "PATCH")
+
+    def delete(self, request: Request, *args: Any, **kwargs: Any) -> HttpResponse:
+        return self._forward(request, "DELETE")
+
+    def head(self, request: Request, *args: Any, **kwargs: Any) -> HttpResponse:
+        return self._forward(request, "HEAD")
+
+    # Django REST framework answers OPTIONS with a Response of its own; this relays
+    # the API server's reply instead.
+    def options(  # type: ignore[override]
+        self, request: Request, *args: Any, **kwargs: Any
+    ) -> HttpResponse:
+        return self._forward(request, "OPTIONS")
+
+    # -- Steps that subclasses can override -----------------------------------
+
+    def parse_path(self, request: Request) -> str:
+        """Return the path on the API server for ``request``.
+
+        Everything after the route is kept as it is, trailing slash included, so
+        ``/my_test_route/items/7/`` becomes ``/get/items/7/``. Slashes around the
+        two settings don't matter.
+        """
+        _, rest = self._split_route(request)
+        target = self.proxy_target_path.strip("/")
+        if target:
+            return f"/{target}{rest}"
+        return rest or "/"
+
+    def get_proxy_path(self, request: Request) -> str:
+        """Return the API server URL for ``request``, without the query string."""
+        url = f"{self.target_api_url.rstrip('/')}{self.parse_path(request)}"
+        logger.debug("Upstream URL: {}", url)
+        return url
+
+    def upstream_headers(self, request: Request) -> dict[str, str]:
+        """Return the headers to send to the API server.
+
+        These are the client's headers, cookies and ``Authorization`` included,
+        without the hop-by-hop ones and those requests sets itself (``Host``,
+        ``Content-Length``, ``Accept-Encoding``). Override it to add an API key or
+        to keep the client's cookies on your site.
+        """
+        return request_headers_to_forward(request.headers, has_body=bool(request.body))
+
+    def send_request(
+        self,
+        method: str,
+        url: str,
+        params: dict[str, Any] | None = None,
+        data: Any = None,
+        json: Any = None,
+        timeout: float | tuple[float, float] = DEFAULT_TIMEOUT,
+        verify: bool | str = True,
+        headers: Mapping[str, str] | None = None,
+        allow_redirects: bool | None = None,
+    ) -> requests.Response:
+        """Send the request to the API server and return its reply.
+
+        Pass-through mode puts the query string in ``url`` and passes the raw body
+        as ``data``, the result of ``upstream_headers()`` as ``headers`` and
+        ``allow_redirects=False``, so an override has to accept those
+        (``**kwargs`` will do).
+        """
+        kwargs: dict[str, Any] = dict(method=method, url=url, params=params, data=data,
+                                      json=json, timeout=timeout, verify=verify)
+        # JSON mode passes neither, and calls requests as it always has (following
+        # redirects).
+        if headers is not None:
+            kwargs["headers"] = dict(headers)
+        if allow_redirects is not None:
+            kwargs["allow_redirects"] = allow_redirects
+        return requests.request(**kwargs)
+
+    def relay_response(self, upstream: requests.Response) -> HttpResponse:
+        """Build the reply for the client from the API server's reply.
+
+        The status code, headers, cookies and body come back as they are, except
+        hop-by-hop headers and those that no longer fit after requests decoded the
+        body (``Content-Encoding``, ``Content-Length``). A ``Location`` header goes
+        through ``rewrite_location()``.
+        """
+        reply = RelayedResponse(upstream.content, status=upstream.status_code,
+                                reason=upstream.reason or None)
+        del reply["Content-Type"]  # only the API server's, if it sent one
+        head = self.request.method == "HEAD"
+        for name, value in response_headers_to_relay(upstream.headers, head=head).items():
+            reply[name] = value
+        location = reply.get("Location")
+        if location:
+            reply["Location"] = self.rewrite_location(self.request, location)
+        for cookie in _set_cookie_headers(upstream):
+            _add_cookie(reply, cookie)
+        return reply
+
+    def rewrite_location(self, request: Request, location: str) -> str:
+        """Point a ``Location`` header of the API server at your site.
+
+        * An address on the API server under ``proxy_target_path`` goes through the
+          proxy route: with the quick start settings, ``https://httpbin.org/get/next``
+          and ``/get/next`` both become ``/my_test_route/next``.
+        * A relative one (``next``, ``../list``, ``?page=2``) stays as it is: the
+          client resolves it against the proxy route, which is right already.
+        * An address on another host stays as it is. One on the API server outside
+          ``proxy_target_path`` (``/login`` above) becomes absolute, so it still
+          leads to the API server.
+        """
+        if not (location.startswith("/") or urlsplit(location).scheme):
+            return location
+        base = urlsplit(self.target_api_url.rstrip("/"))
+        target = self.proxy_target_path.strip("/")
+        base_path = base.path.rstrip("/") + (f"/{target}" if target else "")
+        there = urlsplit(urljoin(f"{base.scheme}://{base.netloc}/", location))
+        same_server = (there.scheme.lower(), there.netloc.lower()) == (
+            base.scheme.lower(), base.netloc.lower())
+        under_target = (not base_path or there.path == base_path
+                        or there.path.startswith(base_path + "/"))
+        if same_server and under_target:
+            try:
+                route, _ = self._split_route(request)
+            except Http404:  # a parse_path() override sent something else here
+                return location
+            path = route + there.path[len(base_path):]
+            return urlunsplit(("", "", path or "/", there.query, there.fragment))
+        if location.startswith("/") and not location.startswith("//"):
+            return urlunsplit(there)  # on the API server, outside the proxied path
+        return location
+
+    # -- Django REST framework hooks ------------------------------------------
+
+    def perform_authentication(self, request: Request) -> None:
+        # Read the body before authentication can: SessionAuthentication's CSRF
+        # check parses forms, and after that a multipart body can't be read again.
+        # (Not earlier: Django REST framework's error handling needs the content
+        # negotiation that runs first, e.g. for a body over DATA_UPLOAD_MAX_MEMORY_SIZE.)
+        _ = request.body
+        super().perform_authentication(request)
+
+    def perform_content_negotiation(self, request: Request, force: bool = False) -> Any:
+        # The API server decides what it answers with, so an Accept header Django
+        # REST framework can't render is not a 406.
+        return super().perform_content_negotiation(request, force=True)
+
+    def finalize_response(self, request: Request, response: Any, *args: Any, **kwargs: Any) -> Any:
+        # Django REST framework would set its own Allow header on every reply and add
+        # Accept to Vary. The replies the proxy builds (the API server's, or a 502/504)
+        # keep their headers; Django REST framework's own (a 403, say) get its headers.
+        if isinstance(response, Response):
+            return super().finalize_response(request, response, *args, **kwargs)
+        return response
+
+    # -- Internals ------------------------------------------------------------
+
+    def _forward(self, request: Request, method: str) -> HttpResponse:
+        """Send ``request`` to the API server as ``method`` and relay the reply."""
+        logger.debug("Proxy {} {}", method, request.path)
+        url = self.get_proxy_path(request)
+        query = request.META.get("QUERY_STRING", "")
+        if query:
+            url = f"{url}?{query}"
+        body = request.body
+        headers = self.upstream_headers(request)
+        logger.debug("Forwarding headers {} and {} bytes of body", sorted(headers), len(body))
+        try:
+            # Redirects go back to the client (see rewrite_location()), cookies and all.
+            upstream = self.send_request(method, url, data=body or None, headers=headers,
+                                         allow_redirects=False)
+        except requests.RequestException as exc:
+            status = NO_ANSWER_IN_TIME if isinstance(exc, requests.Timeout) else NO_ANSWER
+            logger.exception("Could not proxy {} {}: {}. Replying {} {}", method, request.path,
+                             _failure_reason(exc), int(status), ERROR_REPLY_TEXT)
+            return JsonResponse(ERROR_REPLY, status=status)
+        logger.debug("API server answered {} ({}, {} bytes)", upstream.status_code,
+                     _content_type(upstream), len(upstream.content))
+        return self.relay_response(upstream)
+
+    def _split_route(self, request: Request) -> tuple[str, str]:
+        """Split the request path into the proxy route on your site and the rest."""
+        path = escape_uri_path(request.path)
+        route = self.proxy_route_path.strip("/")
+        if not route:
+            return "", path
+        match = re.search("/" + re.escape(route) + "(?=/|$)", path)
+        if match is None:  # e.g. /my_test_routeXYZ, which the README's URLs also send here
+            raise Http404(f"{request.path} is not under /{route}/")
+        return path[:match.end()], path[match.end():]
+
+
+def _set_cookie_headers(upstream: requests.Response) -> list[str]:
+    """Every ``Set-Cookie`` header of the reply; requests joins them into one."""
+    raw_headers = getattr(getattr(upstream, "raw", None), "headers", None)
+    getlist = getattr(raw_headers, "getlist", None)
+    if callable(getlist):
+        return list(getlist("Set-Cookie"))
+    value = upstream.headers.get("Set-Cookie")
+    return [value] if value else []
+
+
+def _add_cookie(reply: HttpResponse, header: str) -> None:
+    name = header.split("=", 1)[0].strip()
+    jar = SimpleCookie()
+    jar.load(header)
+    if name in jar:
+        reply.cookies[name] = jar[name]
+    else:
+        logger.debug("Dropped a Set-Cookie header Python can't parse (cookie {!r})", name)