docs: address review feedback on merge similar endpoints ADR

- Reword "pure REST" alternative per @deborahgu's suggestion: the
  proposed design is already RESTful (certificate_task is the noun,
  POST creates the task, payload specifies the task type)
- Clarify authorization model: preserve the three distinct permissions
  from the legacy endpoints via two-layer enforcement (coarse view-level
  check + per-mode service-level check). Updated implementation
  requirements, view docstring, and code skeleton to reflect this

Author: Abdul Muqadim

docs/decisions/0031-merge-similar-endpoints.rst

@@ -1,7 +1,7 @@
 Merge Similar Endpoints
 =======================
 
-:Status: Proposed
+:Status: Accepted
 :Date: 2026-03-31
 :Deciders: Open edX Platform / API Working Group
 :Technical Story: Open edX REST API Standards - Consolidation of fragmented same-resource endpoints into unified parameterised views
@@ -49,8 +49,12 @@ Implementation requirements:
   applied to that resource.
 * Expose a single URL per resource group accepting an ``action`` or ``mode`` field (or using HTTP
   verbs semantically where REST conventions apply cleanly).
-* Move shared logic — permission checking, input validation, audit logging — into a common service
-  layer or mixin that all operations invoke.
+* Move shared infrastructure, input validation, audit logging, response shaping, and the
+  enforcement machinery for permissions, into a common service layer or mixin that all operations
+  invoke. The distinct authorization requirements of the legacy endpoints must be preserved: the
+  view performs a coarse access check, and each mode handler in the service layer enforces its
+  own specific permission. Consolidation removes duplicated boilerplate; it does not flatten the
+  authorization model.
 * Preserve backward compatibility via URL aliases or deprecation redirects for a defined transition
   window.
 * Document the unified endpoint schema in drf-spectacular / OpenAPI, including the enumerated set
@@ -93,19 +97,35 @@ Valid ``mode`` values: ``generate``, ``regenerate``, ``toggle``.
 
    # lms/djangoapps/instructor/views/api.py
    class CertificateTaskView(APIView):
-       """Unified entry point for certificate generation lifecycle operations."""
+       """
+       Unified entry point for certificate generation lifecycle operations.
+
+       Authorization is enforced in two layers:
+
+       1. A coarse view-level check confirms the caller has instructor-level
+          access to the course at all.
+       2. Per-mode permission checks live inside the corresponding
+          ``CertificateTaskService`` method, preserving the distinct
+          authorization requirements of the legacy endpoints
+          (``enable_certificate_generation``,
+          ``start_certificate_generation``,
+          ``start_certificate_regeneration``).
+       """
 
        VALID_MODES = {"generate", "regenerate", "toggle"}
 
        def post(self, request, course_id):
            course_key = CourseKey.from_string(course_id)
+           # Coarse authorization: must be an instructor on this course.
            _check_instructor_permissions(request.user, course_key)
 
            mode = request.data.get("mode")
            if mode not in self.VALID_MODES:
                raise ValidationError({"mode": f"Must be one of: {self.VALID_MODES}"})
 
-           service = CertificateTaskService(course_key)
+           service = CertificateTaskService(course_key, request.user)
+           # Each service method enforces its own mode-specific permission
+           # before dispatching to the underlying task.
            result = getattr(service, mode)(request.data)
            return Response(result, status=status.HTTP_200_OK)
 
@@ -141,10 +161,9 @@ Alternatives Considered
 
 * **Keep per-action endpoints**: Rejected. The duplication cost compounds with every new operation
   and makes consistent error handling and logging practically impossible to enforce.
-* **Use HTTP verbs exclusively (pure REST)**: Partially applicable — ``POST`` for create,
-  ``DELETE`` for unenroll — but breaks down for operations that do not map cleanly to HTTP verbs
-  (e.g., ``enable_certificate_generation``). A hybrid approach (HTTP verbs where natural,
-  ``action`` / ``mode`` parameter otherwise) is acceptable.
+* **Use HTTP verbs exclusively (pure REST)**: Not applicable. This is already RESTful.
+  The noun is ``certificate_task``, the ``POST`` indicates that we are creating a
+  certificate task, and the payload indicates what the task is going to be.
 * **GraphQL mutations**: Considered but out of scope for this iteration; the platform's existing
   REST ecosystem makes a full GraphQL migration impractical in the near term.