doc: factorize ETag management

Author: azmeuk

doc/guides/_examples/django_example.py

@@ -37,12 +37,19 @@
 
 # -- setup-start --
 def scim_response(payload, status=HTTPStatus.OK):
-    """Build a Django response with the SCIM media type."""
-    return HttpResponse(
+    """Build a Django response with the SCIM media type.
+
+    Automatically sets the ``ETag`` header from ``meta.version`` when present.
+    """
+    response = HttpResponse(
         payload,
         status=status,
         content_type="application/scim+json",
     )
+    meta = json.loads(payload).get("meta", {})
+    if version := meta.get("version"):
+        response["ETag"] = version
+    return response
 
 
 def resource_location(request, app_record):
@@ -139,15 +146,13 @@ def get(self, request, app_record):
             return HttpResponse(status=HTTPStatus.NOT_MODIFIED)
 
         scim_user = to_scim_user(app_record, resource_location(request, app_record))
-        resp = scim_response(
+        return scim_response(
             scim_user.model_dump_json(
                 scim_ctx=Context.RESOURCE_QUERY_RESPONSE,
                 attributes=req.attributes,
                 excluded_attributes=req.excluded_attributes,
             )
         )
-        resp["ETag"] = etag
-        return resp
 
     def delete(self, request, app_record):
         if resp := check_etag(app_record, request):
@@ -180,13 +185,11 @@ def put(self, request, app_record):
         response_user = to_scim_user(
             updated_record, resource_location(request, updated_record)
         )
-        resp = scim_response(
+        return scim_response(
             response_user.model_dump_json(
                 scim_ctx=Context.RESOURCE_REPLACEMENT_RESPONSE
             )
         )
-        resp["ETag"] = make_etag(updated_record)
-        return resp
 
     def patch(self, request, app_record):
         if resp := check_etag(app_record, request):
@@ -208,11 +211,9 @@ def patch(self, request, app_record):
         except SCIMException as error:
             return scim_exception_error(error)
 
-        resp = scim_response(
+        return scim_response(
             scim_user.model_dump_json(scim_ctx=Context.RESOURCE_PATCH_RESPONSE)
         )
-        resp["ETag"] = make_etag(updated_record)
-        return resp
 # -- single-resource-end --
 
 
@@ -261,12 +262,10 @@ def post(self, request):
             return scim_exception_error(error)
 
         response_user = to_scim_user(app_record, resource_location(request, app_record))
-        resp = scim_response(
+        return scim_response(
             response_user.model_dump_json(scim_ctx=Context.RESOURCE_CREATION_RESPONSE),
             HTTPStatus.CREATED,
         )
-        resp["ETag"] = make_etag(app_record)
-        return resp
 
 
 urlpatterns = [

doc/guides/_examples/fastapi_example.py

@@ -1,3 +1,4 @@
+import json
 from http import HTTPStatus
 
 from fastapi import APIRouter
@@ -34,15 +35,21 @@
 
 # -- setup-start --
 app = FastAPI()
-router = APIRouter(prefix="/scim/v2")
 
 
-@app.middleware("http")
-async def add_scim_content_type(request: Request, call_next):
-    """Set the SCIM media type on every response."""
-    response = await call_next(request)
-    response.headers["Content-Type"] = "application/scim+json"
-    return response
+class SCIMResponse(Response):
+    """SCIM JSON response that auto-extracts the ``ETag`` from ``meta.version``."""
+
+    media_type = "application/scim+json"
+
+    def __init__(self, content: str, **kwargs):
+        super().__init__(content=content, **kwargs)
+        meta = json.loads(content).get("meta", {})
+        if version := meta.get("version"):
+            self.headers["ETag"] = version
+
+
+router = APIRouter(prefix="/scim/v2", default_response_class=SCIMResponse)
 
 
 def resource_location(request, app_record):
@@ -87,21 +94,21 @@ def resolve_user(user_id: str):
 async def handle_validation_error(request, error):
     """Turn Pydantic validation errors into SCIM error responses."""
     scim_error = Error.from_validation_error(error.errors()[0])
-    return Response(scim_error.model_dump_json(), status_code=scim_error.status)
+    return SCIMResponse(scim_error.model_dump_json(), status_code=scim_error.status)
 
 
 @app.exception_handler(HTTPException)
 async def handle_http_exception(request, error):
     """Turn HTTP exceptions into SCIM error responses."""
     scim_error = Error(status=error.status_code, detail=error.detail or "")
-    return Response(scim_error.model_dump_json(), status_code=error.status_code)
+    return SCIMResponse(scim_error.model_dump_json(), status_code=error.status_code)
 
 
 @app.exception_handler(SCIMException)
 async def handle_scim_error(request, error):
     """Turn SCIM exceptions into SCIM error responses."""
     scim_error = error.to_error()
-    return Response(scim_error.model_dump_json(), status_code=scim_error.status)
+    return SCIMResponse(scim_error.model_dump_json(), status_code=scim_error.status)
 # -- error-handlers-end --
 # -- refinements-end --
 
@@ -118,13 +125,12 @@ async def get_user(request: Request, app_record: dict = Depends(resolve_user)):
     if_none_match = request.headers.get("If-None-Match")
     if if_none_match and etag in [t.strip() for t in if_none_match.split(",")]:
         return Response(status_code=HTTPStatus.NOT_MODIFIED)
-    return Response(
+    return SCIMResponse(
         scim_user.model_dump_json(
             scim_ctx=Context.RESOURCE_QUERY_RESPONSE,
             attributes=req.attributes,
             excluded_attributes=req.excluded_attributes,
         ),
-        headers={"ETag": etag},
     )
 # -- get-user-end --
 
@@ -144,9 +150,8 @@ async def patch_user(request: Request, app_record: dict = Depends(resolve_user))
     updated_record = from_scim_user(scim_user)
     save_record(updated_record)
 
-    return Response(
+    return SCIMResponse(
         scim_user.model_dump_json(scim_ctx=Context.RESOURCE_PATCH_RESPONSE),
-        headers={"ETag": make_etag(updated_record)},
     )
 # -- patch-user-end --
 
@@ -170,9 +175,8 @@ async def replace_user(request: Request, app_record: dict = Depends(resolve_user
     response_user = to_scim_user(
         updated_record, resource_location(request, updated_record)
     )
-    return Response(
+    return SCIMResponse(
         response_user.model_dump_json(scim_ctx=Context.RESOURCE_REPLACEMENT_RESPONSE),
-        headers={"ETag": make_etag(updated_record)},
     )
 # -- put-user-end --
 
@@ -204,7 +208,7 @@ async def list_users(request: Request):
         items_per_page=len(resources),
         resources=resources,
     )
-    return Response(
+    return SCIMResponse(
         response.model_dump_json(
             scim_ctx=Context.RESOURCE_QUERY_RESPONSE,
             attributes=req.attributes,
@@ -226,10 +230,9 @@ async def create_user(request: Request):
     save_record(app_record)
 
     response_user = to_scim_user(app_record, resource_location(request, app_record))
-    return Response(
+    return SCIMResponse(
         response_user.model_dump_json(scim_ctx=Context.RESOURCE_CREATION_RESPONSE),
         status_code=HTTPStatus.CREATED,
-        headers={"ETag": make_etag(app_record)},
     )
 # -- create-user-end --
 # -- collection-end --
@@ -248,7 +251,7 @@ async def list_schemas(request: Request):
         items_per_page=len(page),
         resources=page,
     )
-    return Response(
+    return SCIMResponse(
         response.model_dump_json(scim_ctx=Context.RESOURCE_QUERY_RESPONSE),
     )
 
@@ -260,8 +263,8 @@ async def get_schema_by_id(schema_id: str):
         schema = get_schema(schema_id)
     except KeyError:
         scim_error = Error(status=404, detail=f"Schema {schema_id!r} not found")
-        return Response(scim_error.model_dump_json(), status_code=HTTPStatus.NOT_FOUND)
-    return Response(
+        return SCIMResponse(scim_error.model_dump_json(), status_code=HTTPStatus.NOT_FOUND)
+    return SCIMResponse(
         schema.model_dump_json(scim_ctx=Context.RESOURCE_QUERY_RESPONSE),
     )
 # -- schemas-end --
@@ -279,7 +282,7 @@ async def list_resource_types(request: Request):
         items_per_page=len(page),
         resources=page,
     )
-    return Response(
+    return SCIMResponse(
         response.model_dump_json(scim_ctx=Context.RESOURCE_QUERY_RESPONSE),
     )
 
@@ -293,8 +296,8 @@ async def get_resource_type_by_id(resource_type_id: str):
         scim_error = Error(
             status=404, detail=f"ResourceType {resource_type_id!r} not found"
         )
-        return Response(scim_error.model_dump_json(), status_code=HTTPStatus.NOT_FOUND)
-    return Response(
+        return SCIMResponse(scim_error.model_dump_json(), status_code=HTTPStatus.NOT_FOUND)
+    return SCIMResponse(
         rt.model_dump_json(scim_ctx=Context.RESOURCE_QUERY_RESPONSE),
     )
 # -- resource-types-end --
@@ -304,7 +307,7 @@ async def get_resource_type_by_id(resource_type_id: str):
 @router.get("/ServiceProviderConfig")
 async def get_service_provider_config():
     """Return the SCIM service provider configuration."""
-    return Response(
+    return SCIMResponse(
         service_provider_config.model_dump_json(
             scim_ctx=Context.RESOURCE_QUERY_RESPONSE
         ),

doc/guides/fastapi.rst

@@ -25,9 +25,9 @@ Application setup
 
 Start with a FastAPI application and an
 `APIRouter <https://fastapi.tiangolo.com/reference/apirouter/>`_ prefixed with ``/scim/v2``.
-The SCIM specifications indicates that the responses content type must be ``application/scim+json``,
-so lets enforce this on all routes with an
-`HTTP middleware <https://fastapi.tiangolo.com/tutorial/middleware/>`_.
+``SCIMResponse`` is a thin :class:`~fastapi.Response` subclass that sets the
+``application/scim+json`` content type and automatically extracts the ``ETag`` header
+from ``meta.version`` when the response body contains it.
 
 .. literalinclude:: _examples/fastapi_example.py
    :language: python
@@ -180,15 +180,16 @@ the record's ETag and raises an :class:`~fastapi.HTTPException` on mismatch.
    :start-after: # -- etag-start --
    :end-before: # -- etag-end --
 
-On ``GET`` single-resource responses, the ``ETag`` header is set and the ``If-None-Match``
+On ``GET`` single-resource responses, the ``If-None-Match``
 request header is checked manually to return a ``304 Not Modified`` when the client already
 has the current version.
 
 On write operations (``PUT``, ``PATCH``, ``DELETE``), the ``If-Match`` header is checked
 before processing.
 If the client's ETag does not match, a ``412 Precondition Failed`` SCIM error is returned.
-``POST`` and ``PUT``/``PATCH`` responses include the ``ETag`` header for the newly created or
-updated resource.
+
+``SCIMResponse`` automatically extracts ``meta.version`` from the serialized body and sets
+the ``ETag`` response header, so endpoints do not need to set it manually.
 
 .. tip::