From 5f0bd3cb7747d3ee57206ef4f22d91336d9b7921 Mon Sep 17 00:00:00 2001
From: Emelia Smith <ThisIsMissEm@users.noreply.github.com>
Date: Tue, 7 May 2024 19:54:14 +0200
Subject: [PATCH] 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 https://github.com/mastodon/mastodon/pull/29092

* Document digest in Admin DomainBlock Entity
---
 content/en/entities/Admin_DomainBlock.md  | 10 ++++++-
 content/en/methods/admin/domain_blocks.md | 36 +++++++++++++++++++----
 2 files changed, 40 insertions(+), 6 deletions(-)

diff --git a/content/en/entities/Admin_DomainBlock.md b/content/en/entities/Admin_DomainBlock.md
index 4b19999a..07ca7aaf 100644
--- 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" >}}
\ No newline at end of file
+{{< 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
index f20ba884..bba8fb5c 100644
--- 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,7 +394,7 @@ DomainBlock with the given ID does not exist
 
 ```json
 {
-	"error": "Record not found"
+  "error": "Record not found"
 }
 ```
 
@@ -376,4 +402,4 @@ DomainBlock with the given ID does not exist
 
 ## 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" >}}
\ No newline at end of file
+{{< 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" >}}