Skip to content

Commit a7e3f33

Browse files
committed
[docs] Add documentation for batch update API endpoint
- Document GET, PUT, and PATCH methods for batch retrieve/update - Clarify that organization field is read-only for existing objects - List all read-only and updatable fields
1 parent 73f9d69 commit a7e3f33

File tree

2 files changed

+57
-1
lines changed

2 files changed

+57
-1
lines changed

docs/user/rest-api.rst

Lines changed: 45 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -820,7 +820,7 @@ This API endpoint allows to use the features described in
820820
This API endpoint allows to use the features described in
821821
:doc:`importing_users` and :doc:`generating_users`.
822822

823-
Responds only to **POST**, used to save a ``RadiusBatch`` instance.
823+
Responds only to **POST**, used to create a ``RadiusBatch`` instance.
824824

825825
It is possible to generate the users of the ``RadiusBatch`` with two
826826
different strategies: csv or prefix.
@@ -856,6 +856,50 @@ When using this strategy, in the response you can find the field
856856
``pdf_link`` which can be used to download a PDF file containing the user
857857
credentials.
858858

859+
Batch retrieve and update
860+
++++++++++++++++++++++++++
861+
862+
.. code-block:: text
863+
864+
/api/v1/radius/batch/<id>/
865+
866+
Responds to **GET**, **PUT**, and **PATCH** methods.
867+
868+
Used to retrieve or update a ``RadiusBatch`` instance.
869+
870+
.. note::
871+
872+
The ``organization`` field is **read-only** for existing batch objects
873+
and cannot be changed via the API. This is intentional as changing
874+
the organization after batch creation would be inconsistent.
875+
876+
Parameters for **GET**:
877+
878+
===== ===========
879+
Param Description
880+
===== ===========
881+
id UUID of the batch
882+
===== ===========
883+
884+
Parameters for **PUT**/**PATCH** (only certain fields can be updated):
885+
886+
=============== ================================================
887+
Param Description
888+
=============== ================================================
889+
name Name of the operation
890+
expiration_date Date of expiration of the users (can be updated)
891+
=============== ================================================
892+
893+
Fields that are **read-only** and cannot be updated:
894+
895+
- ``organization`` - Cannot be changed after creation
896+
- ``strategy`` - Cannot be changed after creation
897+
- ``csvfile`` - Cannot be changed after creation
898+
- ``prefix`` - Cannot be changed after creation
899+
- ``users`` - Managed automatically
900+
- ``user_credentials`` - Generated automatically
901+
- ``created``, ``modified`` - Timestamps
902+
859903
Batch CSV Download
860904
++++++++++++++++++
861905

openwisp_radius/api/serializers.py

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -459,11 +459,23 @@ class RadiusBatchUpdateSerializer(RadiusBatchSerializer):
459459
Makes the organization field readonly for existing objects.
460460
"""
461461

462+
organization_slug = RadiusOrganizationField(
463+
help_text=("Slug of the organization for creating radius batch."),
464+
required=False,
465+
label="organization",
466+
slug_field="slug",
467+
write_only=True,
468+
)
469+
462470
def validate(self, data):
463471
"""
464472
Simplified validation for partial updates.
465473
Only validates essential fields based on strategy.
474+
Ignores organization_slug if provided since organization is readonly.
466475
"""
476+
# Remove organization_slug from data if provided (should not be changeable)
477+
data.pop("organization_slug", None)
478+
467479
strategy = data.get("strategy") or (self.instance and self.instance.strategy)
468480

469481
if (

0 commit comments

Comments
 (0)