Add missing documentation for linkintegrity endpoint

docs/source/endpoints/linkintegrity.md

@@ -13,25 +13,35 @@ When you create relations between content objects in Plone (for example, via rel
 The Plone user interface will use those stored relations to show a warning when you try to delete a content object that is still referenced elsewhere.
 Link integrity avoids broken links ("breaches") in the site.
 
-This check includes content objects that are located within a content object ("folderish content").
+The `@linkintegrity` endpoint returns the list of reference breaches
+that would happen if some content items would be deleted.
+This information can be used to show the editor a confirmation dialog.
 
-The `@linkintegrity` endpoint returns the list of reference breaches.
-If there are none, it will return an empty list (`[]`).
+This check includes content objects that are located within a content object ("folderish content").
 
-You can call the `/@linkintegrity` endpoint on the site root with a `GET` request and a list of UIDs in the JSON body:
+You can call the `/@linkintegrity` endpoint on the site root with a `GET` request and a list of content UIDs in the JSON body:
 
 ```{eval-rst}
 ..  http:example:: curl httpie python-requests
     :request: ../../../src/plone/restapi/tests/http-examples/linkintegrity_get.req
 ```
 
+The endpoint accepts a single parameter:
+
+`uids`
+: A list of object UIDs that you want to check.
+
 The server will respond with the result:
 
 ```{literalinclude} ../../../src/plone/restapi/tests/http-examples/linkintegrity_get.resp
    :language: http
 ```
 
-The endpoint accepts a single parameter:
+The result includes a list of objects corresponding to the UIDs that were requested.
+Each result object includes:
 
-`uids`
-: A list of object UIDs that you want to check.
+`breaches`
+: A list of breaches (sources of relations that would be broken)
+
+`items_total`
+: Count of items contained inside the specified UIDs.

src/plone/restapi/tests/http-examples/linkintegrity_get.req

@@ -1,3 +1,3 @@
-GET /plone/@linkintegrity?uids=SomeUUID000000000000000000000001 HTTP/1.1
+GET /plone/@linkintegrity?uids=SomeUUID000000000000000000000002 HTTP/1.1
 Accept: application/json
 Authorization: Basic YWRtaW46c2VjcmV0

src/plone/restapi/tests/http-examples/linkintegrity_get.resp

@@ -1 +1,20 @@
-TODO
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+[
+    {
+        "@id": "http://localhost:55001/plone/doc-2",
+        "@type": "Document",
+        "breaches": [
+            {
+                "@id": "http://localhost:55001/plone/doc-1",
+                "title": "First document",
+                "uid": "SomeUUID000000000000000000000001"
+            }
+        ],
+        "description": "",
+        "items_total": 0,
+        "review_state": "private",
+        "title": "Second document"
+    }
+]

src/plone/restapi/tests/test_documentation.py

@@ -31,11 +31,15 @@
 from plone.restapi.tests.statictime import StaticTime
 from plone.testing.zope import Browser
 from plone.uuid.interfaces import IUUID
+from z3c.relationfield import RelationValue
 from zope.component import createObject
 from zope.component import getMultiAdapter
 from zope.component import getUtility
 from zope.component.hooks import getSite
+from zope.event import notify
 from zope.interface import alsoProvides
+from zope.intid.interfaces import IIntIds
+from zope.lifecycleevent import ObjectModifiedEvent
 
 import collections
 import json
@@ -2713,3 +2717,27 @@ def test_controlpanels_crud_rules(self):
         url = "/@controlpanels/content-rules/rule-3"
         response = self.api_session.delete(url)
         save_request_and_response_for_docs("controlpanels_delete_rule", response)
+
+
+class TestLinkintegrity(TestDocumentationBase):
+
+    layer = PLONE_RESTAPI_DX_FUNCTIONAL_TESTING
+
+    def setUp(self):
+        super().setUp()
+
+        # Create one document with a reference to another
+        self.doc1 = createContentInContainer(
+            self.portal, "Document", id="doc-1", title="First document"
+        )
+        self.doc2 = createContentInContainer(
+            self.portal, "Document", id="doc-2", title="Second document"
+        )
+        intids = getUtility(IIntIds)
+        self.doc1.relatedItems = [RelationValue(intids.getId(self.doc2))]
+        notify(ObjectModifiedEvent(self.doc1))
+        transaction.commit()
+
+    def test_linkintegrity_get(self):
+        response = self.api_session.get("/@linkintegrity?uids=" + self.doc2.UID())
+        save_request_and_response_for_docs("linkintegrity_get", response)