From 5af97afe2e37f490a4172a9258fce1ca99cf97ba Mon Sep 17 00:00:00 2001
From: Rahul Shinde <shinde.r.a@gmail.com>
Date: Wed, 23 Jul 2025 18:10:43 +0530
Subject: [PATCH] docs(api): Add usage guide for API-aware entity locking

---
 docs/components/api.rst | 85 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 85 insertions(+)

diff --git a/docs/components/api.rst b/docs/components/api.rst
index e5a0c072..77a4b9ba 100644
--- a/docs/components/api.rst
+++ b/docs/components/api.rst
@@ -97,3 +97,88 @@ The API controller should extend ``Mautic\ApiBundle\Controller\CommonApiControll
             return $this->handleView($worlds);
         }
     }
+
+----
+
+.. vale off
+
+API-aware entity locking
+****************************
+
+.. vale on
+
+Mautic supports locking for API-editable entities, such as Emails, to prevent overwriting changes while a user is actively editing the entity in the UI.
+
+This is useful when:
+
+- You want the API to respect the locking behavior already in place in the UI.
+- You want to return a `409 Conflict` when a record is locked.
+
+.. vale off
+
+Enable API lock for a model
+============================
+
+.. vale on
+
+To make an entity model API-lock-aware:
+
+1. Implement the interface:
+
+.. code-block:: php
+
+    use Mautic\ApiBundle\Model\ApiLockAwareInterface;
+
+    class MyEntityModel implements ApiLockAwareInterface
+    {
+        // ...
+    }
+
+2. Use the trait to reuse locking logic:
+
+.. code-block:: php
+
+    use Mautic\ApiBundle\Model\ApiEntityLockTrait;
+
+    class MyEntityModel implements ApiLockAwareInterface
+    {
+        use ApiEntityLockTrait;
+
+        // Optional: Override `isApiLocked()` if you need custom behavior
+    }
+
+This ensures your model will be checked by the API when editing.
+
+Behind the scenes, the API controller checks:
+
+.. code-block:: php
+
+    if ($this->model instanceof ApiLockAwareInterface && $this->model->isApiLocked($entity)) {
+        ....
+    }
+
+.. vale off
+
+Error message
+=============
+
+.. vale on
+
+When an entity is locked, the API returns:
+
+.. code-block:: json
+
+    {
+      "errors": [
+        {
+          "message": "{Entity} is currently checked out by {User} (on {Date} at {Time}).",
+          "code": 409,
+          "details": {
+            "checkedOutBy": "{User}",
+            "checkedOut": "{Date} {Time}"
+          }
+        }
+      ]
+    }
+
+This format helps client apps identify locked records and avoid overwriting.