Merge pull request #5166 from netbox-community/4882-api-bulk-update

#4882: Support bulk updates via REST API

docs/release-notes/version-2.10.md

@@ -6,6 +6,20 @@
 
 ### New Features
 
+#### REST API Bulk Deletion ([#3436](https://github.com/netbox-community/netbox/issues/3436))
+
+The REST API now supports the bulk deletion of objects of the same type in a single request. Send a `DELETE` HTTP request to the list to the model's list endpoint (e.g. `/api/dcim/sites/`) with a list of JSON objects specifying the numeric ID of each object to be deleted. For example, to delete sites with IDs 10, 11, and 12, issue the following request:
+
+```no-highlight
+curl -s -X DELETE \
+-H "Authorization: Token $TOKEN" \
+-H "Content-Type: application/json" \
+http://netbox/api/dcim/sites/ \
+--data '[{"id": 10}, {"id": 11}, {"id": 12}]'
+```
+
+### Enhancements
+
 * [#1503](https://github.com/netbox-community/netbox/issues/1503) - Allow assigment of secrets to virtual machines
 * [#1692](https://github.com/netbox-community/netbox/issues/1692) - Allow assigment of inventory items to parent items in web UI
 * [#2179](https://github.com/netbox-community/netbox/issues/2179) - Support the assignment of multiple port numbers for services
@@ -23,6 +37,7 @@
 
 ### REST API Changes
 
+* Added support for `DELETE` operations on list endpoints
 * dcim.Cable: Added `custom_fields`
 * dcim.InventoryItem: The `_depth` field has been added to reflect MPTT positioning
 * dcim.PowerPanel: Added `custom_fields`

docs/rest-api/overview.md

@@ -468,16 +468,16 @@ http://netbox/api/dcim/sites/ \
 ]
 ```
 
-### Modifying an Object
+### Updating an Object
 
 To modify an object which has already been created, make a `PATCH` request to the model's _detail_ endpoint specifying its unique numeric ID. Include any data which you wish to update on the object. As with object creation, the `Authorization` and `Content-Type` headers must also be specified.
 
 ```no-highlight
 curl -s -X PATCH \
-> -H "Authorization: Token $TOKEN" \
-> -H "Content-Type: application/json" \
-> http://netbox/api/ipam/prefixes/18691/ \
-> --data '{"status": "reserved"}' | jq '.'
+-H "Authorization: Token $TOKEN" \
+-H "Content-Type: application/json" \
+http://netbox/api/ipam/prefixes/18691/ \
+--data '{"status": "reserved"}' | jq '.'
 ```
 
 ```json
@@ -515,6 +515,23 @@ curl -s -X PATCH \
 !!! note "PUT versus PATCH"
     The NetBox REST API support the use of either `PUT` or `PATCH` to modify an existing object. The difference is that a `PUT` request requires the user to specify a _complete_ representation of the object being modified, whereas a `PATCH` request need include only the attributes that are being updated. For most purposes, using `PATCH` is recommended.
 
+### Updating Multiple Objects
+
+Multiple objects can be updated simultaneously by issuing a `PUT` or `PATCH` request to a model's list endpoint with a list of dictionaries specifying the numeric ID of each object to be deleted and the attributes to be updated. For example, to update sites with IDs 10 and 11 to a status of "active", issue the following request:
+
+```no-highlight
+curl -s -X PATCH \
+-H "Authorization: Token $TOKEN" \
+-H "Content-Type: application/json" \
+http://netbox/api/dcim/sites/ \
+--data '[{"id": 10, "status": "active"}, {"id": 11, "status": "active"}]'
+```
+
+Note that there is no requirement for the attributes to be identical among objects. For instance, it's possible to update the status of one site along with the name of another in the same request.
+
+!!! note
+    The bulk update of objects is an all-or-none operation, meaning that if NetBox fails to successfully update any of the specified objects (e.g. due a validation error), the entire operation will be aborted and none of the objects will be updated.
+
 ### Deleting an Object
 
 To delete an object from NetBox, make a `DELETE` request to the model's _detail_ endpoint specifying its unique numeric ID. The `Authorization` header must be included to specify an authorization token, however this type of request does not support passing any data in the body.
@@ -537,6 +554,7 @@ NetBox supports the simultaneous deletion of multiple objects of the same type b
 ```no-highlight
 curl -s -X DELETE \
 -H "Authorization: Token $TOKEN" \
+-H "Content-Type: application/json" \
 http://netbox/api/dcim/sites/ \
 --data '[{"id": 10}, {"id": 11}, {"id": 12}]'
 ```

netbox/circuits/tests/test_api.py

@@ -32,6 +32,9 @@ class ProviderTest(APIViewTestCases.APIViewTestCase):
             'slug': 'provider-6',
         },
     ]
+    bulk_update_data = {
+        'asn': 1234,
+    }
 
     @classmethod
     def setUpTestData(cls):
@@ -61,6 +64,9 @@ class CircuitTypeTest(APIViewTestCases.APIViewTestCase):
             'slug': 'circuit-type-6',
         },
     )
+    bulk_update_data = {
+        'description': 'New description',
+    }
 
     @classmethod
     def setUpTestData(cls):
@@ -76,6 +82,9 @@ def setUpTestData(cls):
 class CircuitTest(APIViewTestCases.APIViewTestCase):
     model = Circuit
     brief_fields = ['cid', 'id', 'url']
+    bulk_update_data = {
+        'status': 'planned',
+    }
 
     @classmethod
     def setUpTestData(cls):