[feature] Add REST API list, detail, and delete endpoints for RADIUS batch user creation #771

docs/user/rest-api.rst

@@ -869,12 +869,49 @@ This API endpoint allows to use the features described in
 
     /api/v1/radius/batch/
 
+GET
+^^^
+
+Returns a list of batch user creation operations for the organizations
+managed by the requesting user. Results are paginated and can be filtered.
+
+.. code-block:: text
+
+    /api/v1/radius/batch?search=<batch_name>
+    /api/v1/radius/batch?organization=<org_id>
+    /api/v1/radius/batch?strategy=prefix
+
+Filters
+"""""""
+
+================= ===============================
+Filter Parameter  Description
+================= ===============================
+search            Search batches by name
+organization      Filter by organization id
+organization_slug Filter by organization slug
+strategy          Filter by strategy (prefix/csv)
+================= ===============================
+
+Pagination
+""""""""""
+
+Pagination is provided using page number pagination, the default page size
+is 20, which can be overridden using the ``page_size`` parameter, up to
+:ref:`OPENWISP_API_MAX_PAGE_SIZE <openwisp_api_max_page_size>` (100 by
+default).
+
 .. note::
 
-    This API endpoint allows to use the features described in
-    :doc:`importing_users` and :doc:`generating_users`.
+    The list response does not include ``user_credentials`` to avoid
+    repeatedly exposing plaintext credentials. Use the batch creation
+    response or the protected PDF download endpoint for credentials.
 
-Responds only to **POST**, used to save a ``RadiusBatch`` instance.
+POST
+^^^^
+
+Creates a batch of users using a csv file or generates users with a given
+prefix.
 
 It is possible to generate the users of the ``RadiusBatch`` with two
 different strategies: csv or prefix.
@@ -919,6 +956,43 @@ group by organization before sending its UUID in the ``group`` parameter.
 The ``group`` and ``notes`` parameters are optional. When ``group`` is
 omitted, users retain the standard default-group behavior.
 
+.. note::
+
+    The synchronous ``201 Created`` response for prefix-generated batches
+    includes ``user_credentials``. The asynchronous ``202 Accepted``
+    response does not include credentials; use the ``pdf_link`` after
+    completion.
+
+Batch Detail
+++++++++++++
+
+.. code-block:: text
+
+    /api/v1/radius/batch/<uuid>/
+
+GET
+^^^
+
+Returns a single batch user creation operation by its UUID. The response
+does not include ``user_credentials``.
+
+For completed prefix batches, the response includes a ``pdf_link`` field
+pointing to the protected PDF download endpoint. For CSV batches with an
+uploaded file, the response includes a ``csv_link`` field pointing to the
+protected CSV download endpoint.
+
+DELETE
+^^^^^^
+
+Deletes a batch user creation operation and its associated users. Returns
+``204 No Content`` on success.
+
+.. note::
+
+    Deletion is rejected while the batch ``status`` is ``processing``. The
+    API returns a ``409 Conflict`` response with a clear error message in
+    this case. Pending, completed, and failed batches can be deleted.
+
 Batch CSV Download
 ++++++++++++++++++
 

openwisp_radius/admin.py

@@ -506,11 +506,28 @@ def get_actions(self, request):
 
     @admin.action(description=_("Delete selected batches"), permissions=["delete"])
     def delete_selected_batches(self, request, queryset):
+        skipped = 0
+        deleted = 0
         for obj in queryset:
+            if obj.status == RadiusBatch.PROCESSING:
+                skipped += 1
+                continue
             obj.delete()
-        self.message_user(
-            request, "Successfully deleted selected batches.", level=messages.SUCCESS
-        )
+            deleted += 1
+        if skipped:
+            self.message_user(
+                request,
+                _(
+                    "Skipped {count} batch(es) that are currently being processed."
+                ).format(count=skipped),
+                level=messages.WARNING,
+            )
+        if deleted:
+            self.message_user(
+                request,
+                _("Successfully deleted {count} batch(es).").format(count=deleted),
+                level=messages.SUCCESS,
+            )
 
     def get_readonly_fields(self, request, obj=None):
         readonly_fields = super(RadiusBatchAdmin, self).get_readonly_fields(

openwisp_radius/api/serializers.py

@@ -562,6 +562,66 @@ class Meta:
         read_only_fields = ("status", "user_credentials", "created", "modified")
 
 
+class BatchUserSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = User
+        fields = (
+            "id",
+            "username",
+            "email",
+            "first_name",
+            "last_name",
+        )
+        read_only_fields = fields
+
+
+class RadiusBatchReadSerializer(serializers.ModelSerializer):
+    organization = serializers.PrimaryKeyRelatedField(read_only=True)
+    users = BatchUserSerializer(many=True, read_only=True)
+    pdf_link = serializers.SerializerMethodField(required=False, read_only=True)
+    csv_link = serializers.SerializerMethodField(required=False, read_only=True)
+    status = serializers.CharField(read_only=True)
+
+    def get_pdf_link(self, obj):
+        if obj.strategy == "prefix" and obj.status == RadiusBatch.COMPLETED:
+            request = self.context.get("request")
+            return request.build_absolute_uri(
+                reverse(
+                    "radius:download_rad_batch_pdf",
+                    args=[obj.organization.slug, obj.pk],
+                )
+            )
+        return None
+
+    def get_csv_link(self, obj):
+        if obj.csvfile:
+            request = self.context.get("request")
+            csv_url = reverse(
+                "radius:radius_organization_batch_csv_read",
+                args=[obj.organization.slug, obj.pk],
+            )
+            return request.build_absolute_uri(csv_url)
+        return None
+
+    class Meta:
+        model = RadiusBatch
+        fields = (
+            "id",
+            "organization",
+            "name",
+            "strategy",
+            "status",
+            "expiration_date",
+            "prefix",
+            "users",
+            "pdf_link",
+            "csv_link",
+            "created",
+            "modified",
+        )
+        read_only_fields = fields
+
+
 class RegisterSerializer(
     ErrorDictMixin,
     AllowedMobilePrefixMixin,

openwisp_radius/api/urls.py

@@ -88,6 +88,11 @@ def get_view(name):
                 name="update_registered_user_registration_method",
             ),
             path("radius/batch/", get_view("batch"), name="batch"),
+            path(
+                "radius/batch/<uuid:pk>/",
+                get_view("batch_detail"),
+                name="radius_batch_detail",
+            ),
             path(
                 "radius/organization/<slug:slug>/batch/<uuid:pk>/pdf/",
                 get_view("download_rad_batch_pdf"),

openwisp_radius/api/views.py

@@ -23,14 +23,15 @@
 from rest_framework.authentication import SessionAuthentication
 from rest_framework.authtoken.models import Token as UserToken
 from rest_framework.authtoken.views import ObtainAuthToken as BaseObtainAuthToken
-from rest_framework.exceptions import NotFound, PermissionDenied
+from rest_framework.exceptions import APIException, NotFound, PermissionDenied
 from rest_framework.filters import SearchFilter
 from rest_framework.generics import (
     CreateAPIView,
     GenericAPIView,
     ListAPIView,
     ListCreateAPIView,
     RetrieveAPIView,
+    RetrieveDestroyAPIView,
     RetrieveUpdateDestroyAPIView,
     get_object_or_404,
 )
@@ -78,6 +79,7 @@
     AuthTokenSerializer,
     ChangePhoneNumberSerializer,
     RadiusAccountingSerializer,
+    RadiusBatchReadSerializer,
     RadiusBatchSerializer,
     RadiusGroupSerializer,
     RadiusUserGroupSerializer,
@@ -120,20 +122,53 @@ class ThrottledAPIMixin(object):
     throttle_scope = "others"
 
 
-class BatchView(ThrottledAPIMixin, CreateAPIView):
-    authentication_classes = (BearerAuthentication, SessionAuthentication)
-    permission_classes = (IsAdminUser, DjangoModelPermissions)
-    queryset = RadiusBatch.objects.all()
-    serializer_class = RadiusBatchSerializer
+class RadiusBatchFilter(OrganizationManagedFilter, filters.FilterSet):
+    class Meta(OrganizationManagedFilter.Meta):
+        model = RadiusBatch
+        fields = [*OrganizationManagedFilter.Meta.fields, "strategy"]
 
-    def post(self, request, *args, **kwargs):
-        """
+
+@method_decorator(
+    name="get",
+    decorator=swagger_auto_schema(
+        operation_description="""
+        Returns a list of batch user creation operations for the
+        organizations managed by the user.
+        """,
+    ),
+)
+@method_decorator(
+    name="post",
+    decorator=swagger_auto_schema(
+        operation_description="""
         **Requires the user auth token (Bearer Token).**
         Allows organization administrators to create
         a batch of users using a csv file or generate users
         with a given prefix.
-        """
-        serializer = self.get_serializer(data=request.data)
+        """,
+        request_body=RadiusBatchSerializer,
+        responses={201: RadiusBatchSerializer, 202: RadiusBatchSerializer},
+    ),
+)
+class BatchView(ThrottledAPIMixin, FilterByOrganizationManaged, ListCreateAPIView):
+    authentication_classes = (BearerAuthentication, SessionAuthentication)
+    permission_classes = (IsAdminUser, DjangoModelPermissions)
+    queryset = (
+        RadiusBatch.objects.select_related("organization")
+        .prefetch_related("users")
+        .order_by("-created")
+    )
+    serializer_class = RadiusBatchReadSerializer
+    filterset_class = RadiusBatchFilter
+    filter_backends = [DjangoFilterBackend, SearchFilter]
+    search_fields = ["name"]
+    pagination_class = OpenWispPagination
+    pagination_page_size = 20
+
+    def post(self, request, *args, **kwargs):
+        serializer = RadiusBatchSerializer(
+            data=request.data, context={"request": request}
+        )
         if serializer.is_valid():
             valid_data = serializer.validated_data.copy()
             num_of_users = valid_data.get("number_of_users", 0)
@@ -142,7 +177,9 @@ def post(self, request, *args, **kwargs):
             batch = serializer.save(organization=organization)
             is_async = batch.schedule_processing(number_of_users=num_of_users)
             batch.refresh_from_db()
-            response_serializer = self.get_serializer(batch)
+            response_serializer = RadiusBatchSerializer(
+                batch, context={"request": request}
+            )
             status_code = (
                 status.HTTP_202_ACCEPTED if is_async else status.HTTP_201_CREATED
             )
@@ -196,6 +233,54 @@ def get(self, request, *args, **kwargs):
 download_rad_batch_pdf = DownloadRadiusBatchPdfView.as_view()
 
 
+class Conflict(APIException):
+    status_code = status.HTTP_409_CONFLICT
+    default_detail = _("Conflict.")
+    default_code = "conflict"
+
+
+@method_decorator(
+    name="get",
+    decorator=swagger_auto_schema(
+        operation_description="""
+        Returns a batch user creation operation by its UUID.
+        """,
+    ),
+)
+@method_decorator(
+    name="delete",
+    decorator=swagger_auto_schema(
+        operation_description="""
+        Deletes a batch user creation operation and its associated users.
+        Cannot delete a batch while it is being processed.
+        """,
+        responses={204: "No Content", 409: "Conflict"},
+    ),
+)
+class BatchDetailView(
+    ProtectedAPIMixin, FilterByOrganizationManaged, RetrieveDestroyAPIView
+):
+    authentication_classes = (BearerAuthentication, SessionAuthentication)
+    permission_classes = (IsAdminUser, DjangoModelPermissions)
+    queryset = RadiusBatch.objects.select_related("organization").prefetch_related(
+        "users"
+    )
+    serializer_class = RadiusBatchReadSerializer
+
+    def perform_destroy(self, instance):
+        if instance.status == RadiusBatch.PROCESSING:
+            raise Conflict(
+                _(
+                    "The radius batch object is currently being processed"
+                    " and cannot be deleted."
+                )
+            )
+        instance.delete()
+
+
+batch_detail = BatchDetailView.as_view()
+
+
 class UserDetailsUpdaterMixin(object):
     def update_user_details(self, user):
         language = get_language_from_request(self.request)