Update admin/domain_blocks to include conflict response (#1417)

* Update admin/domain_blocks to include conflict response When creating a domain block, if there is already a domain block rule for the domain, then the existing block is returned. This documents that behavior. I've also documented the `digest` property which was added in mastodon/mastodon#29092 * Document digest in Admin DomainBlock Entity
mastodon · May 7, 2024 · 5f0bd3c · 5f0bd3c
1 parent 59c5876
commit 5f0bd3c
Show file tree

Hide file tree

Showing 2 changed files with 40 additions and 6 deletions.
diff --git a/content/en/entities/Admin_DomainBlock.md b/content/en/entities/Admin_DomainBlock.md
@@ -22,6 +22,7 @@ aliases: [
 {
   "id": "1",
   "domain": "example.com",
+  "digest": "a379a6f6eeafb9a55e378c118034e2751e682fab9f2d30ab13d2125586ce1947",
   "created_at": "2022-11-16T08:15:34.238Z",
   "severity": "noop",
   "reject_media": false,
@@ -48,6 +49,13 @@ aliases: [
 **Version history:**\
 4.0.0 - added
 
+### `digest` {#digest}
+
+**Description:** The sha256 hex digest of the domain that is not allowed to federated.\
+**Type:** String\
+**Version history:**\
+4.3.0 - added
+
 ### `created_at` {#created_at}
 
 **Description:** When the domain was blocked from federating.\
@@ -104,4 +112,4 @@ aliases: [
 
 {{< page-relref page="methods/admin/domain_blocks" caption="admin/domain_blocks API methods" >}}
 
-{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/domain_block_serializer.rb" caption="app/serializers/rest/admin/domain_block_serializer.rb" >}}
+{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/admin/domain_block_serializer.rb" caption="app/serializers/rest/admin/domain_block_serializer.rb" >}}
diff --git a/content/en/methods/admin/domain_blocks.md b/content/en/methods/admin/domain_blocks.md
@@ -60,6 +60,7 @@ limit
   {
     "id": "1",
     "domain": "example.com",
+    "digest": "a379a6f6eeafb9a55e378c118034e2751e682fab9f2d30ab13d2125586ce1947",
     "created_at": "2022-11-16T08:15:34.238Z",
     "severity": "noop",
     "reject_media": false,
@@ -120,6 +121,7 @@ Authorization
 {
   "id": "1",
   "domain": "example.com",
+  "digest": "a379a6f6eeafb9a55e378c118034e2751e682fab9f2d30ab13d2125586ce1947",
   "created_at": "2022-11-16T08:15:34.238Z",
   "severity": "noop",
   "reject_media": false,
@@ -146,7 +148,7 @@ DomainBlock with the given ID does not exist
 
 ```json
 {
-	"error": "Record not found"
+  "error": "Record not found"
 }
 ```
 
@@ -205,6 +207,7 @@ Domain has been blocked from federating.
 {
   "id": "1",
   "domain": "example.com",
+  "digest": "a379a6f6eeafb9a55e378c118034e2751e682fab9f2d30ab13d2125586ce1947",
   "created_at": "2022-11-16T08:15:34.238Z",
   "severity": "noop",
   "reject_media": false,
@@ -225,13 +228,35 @@ Authorized user is not allowed to perform this action, or invalid or missing Aut
 }
 ```
 
-##### 422: Unprocessable entity
+##### 422: Unprocessable entity - Missing Parameter
 
 The domain parameter was not provided
 
 ```json
 {
-	"error": "Validation failed: Domain can't be blank"
+  "error": "Validation failed: Domain can't be blank"
+}
+```
+
+##### 422: Unprocessable entity - Existing Domain Block
+
+The domain parameter already is covered by an existing domain block.
+
+```json
+{
+  "error": "You have already imposed stricter limits on example.com."
+  "existing_domain_block": {
+    "id": "1",
+    "domain": "example.com",
+    "digest": "a379a6f6eeafb9a55e378c118034e2751e682fab9f2d30ab13d2125586ce1947",
+    "created_at": "2022-11-16T08:15:34.238Z",
+    "severity": "noop",
+    "reject_media": false,
+    "reject_reports": false,
+    "private_comment": null,
+    "public_comment": null,
+    "obfuscate": false
+  }
 }
 ```
 
@@ -292,6 +317,7 @@ Domain block has been updated
 {
   "id": "1",
   "domain": "example.com",
+  "digest": "a379a6f6eeafb9a55e378c118034e2751e682fab9f2d30ab13d2125586ce1947",
   "created_at": "2022-11-16T08:15:34.238Z",
   "severity": "noop",
   "reject_media": false,
@@ -368,12 +394,12 @@ DomainBlock with the given ID does not exist
 
 ```json
 {
-	"error": "Record not found"
+  "error": "Record not found"
 }
 ```
 
 ---
 
 ## See also
 
-{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/admin/domain_blocks_controller.rb" caption="app/controllers/api/v1/admin/domain_blocks_controller.rb" >}}
+{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/admin/domain_blocks_controller.rb" caption="app/controllers/api/v1/admin/domain_blocks_controller.rb" >}}