@aliases Endpoint

docs/source/aliases.md

@@ -0,0 +1,132 @@
+---
+html_meta:
+  "description": "Aliases - a mechanism to redirect old URLs to new ones."
+  "property=og:description": "Aliases - a mechanism to redirect old URLs to new ones."
+  "property=og:title": "Aliases"
+  "keywords": "Plone, plone.app.redirector, redirector, REST, API, Aliases"
+---
+
+# Aliases
+
+A mechanism to redirect old URLs to new ones.
+
+When an object is moved (renamed or cut/pasted into a different location), the redirection storage will remember the old path. It is smart enough to deal with transitive references (if we have a -> b and then add b -> c, it is replaced by a reference a -> c) and circular references (attempting to add a -> a does nothing).
+
+The API consumer can create, read, and delete aliases.
+
+
+| Verb     | URL         | Action                                 |
+| -------- | ----------- | -------------------------------------- |
+| `POST`   | `/@aliases` | Add one or more aliases                |
+| `GET`    | `/@aliases` | List all aliases                       |
+| `DELETE` | `/@aliases` | Remove one or more aliases             |
+
+## Adding new URL aliases for a Page
+
+By default, Plone automatically creates a new alias when an object is renamed or moved. Still, you can also create aliases manually.
+
+To create a new alias, send a `POST` request to the `/@aliases` endpoint:
+
+```{eval-rst}
+..  http:example:: curl httpie python-requests
+    :request: ../../src/plone/restapi/tests/http-examples/aliases_add.req
+```
+
+Response:
+
+```{literalinclude} ../../src/plone/restapi/tests/http-examples/aliases_add.resp
+:language: http
+```
+
+## Listing URL aliases of a Page
+
+To list aliases, you can send a `GET` request to the `/@aliases` endpoint:
+
+```{eval-rst}
+..  http:example:: curl httpie python-requests
+    :request: ../../src/plone/restapi/tests/http-examples/aliases_get.req
+```
+
+Response:
+
+```{literalinclude} ../../src/plone/restapi/tests/http-examples/aliases_get.resp
+:language: http
+```
+
+
+## Removing URL aliases of a Page
+
+To remove aliases, send a `DELETE` request to the `/@aliases` endpoint:
+
+```{eval-rst}
+..  http:example:: curl httpie python-requests
+    :request: ../../src/plone/restapi/tests/http-examples/aliases_delete.req
+```
+
+Response:
+
+```{literalinclude} ../../src/plone/restapi/tests/http-examples/aliases_delete.resp
+:language: http
+```
+
+## Adding URL aliases in bulk
+
+You can add multiple URL aliases for multiple pages by sending a `POST` request to the `/@aliases` endpoint on site `root`. **datetime** parameter is optional:
+
+```{eval-rst}
+..  http:example:: curl httpie python-requests
+    :request: ../../src/plone/restapi/tests/http-examples/aliases_root_add.req
+```
+
+Response:
+
+```{literalinclude} ../../src/plone/restapi/tests/http-examples/aliases_root_add.resp
+:language: http
+```
+
+
+## Listing all available aliases
+
+To list all aliases, send a `GET` request to the `/@aliases` endpoint on site `root`:
+
+```{eval-rst}
+..  http:example:: curl httpie python-requests
+    :request: ../../src/plone/restapi/tests/http-examples/aliases_root_get.req
+```
+
+Response:
+
+```{literalinclude} ../../src/plone/restapi/tests/http-examples/aliases_root_get.resp
+:language: http
+```
+
+## Filter aliases
+
+To search for specific aliases, send a `GET` request to the `/@aliases` endpoint on site `root` with a `q` parameter:
+
+```{eval-rst}
+..  http:example:: curl httpie python-requests
+    :request: ../../src/plone/restapi/tests/http-examples/aliases_root_filter.req
+```
+
+Response:
+
+```{literalinclude} ../../src/plone/restapi/tests/http-examples/aliases_root_filter.resp
+:language: http
+```
+
+
+## Bulk removing aliases
+
+To bulk remove aliases send a `DELETE` request to the `/@aliases` endpoint on site `root`:
+
+```{eval-rst}
+..  http:example:: curl httpie python-requests
+    :request: ../../src/plone/restapi/tests/http-examples/aliases_root_delete.req
+```
+
+Response:
+
+```{literalinclude} ../../src/plone/restapi/tests/http-examples/aliases_root_delete.resp
+:language: http
+```

docs/source/index.md

@@ -34,6 +34,7 @@ expansion
 actions
 workflow
 workingcopy
+aliases
 locking
 sharing
 registry

news/1393.feature

@@ -0,0 +1,2 @@
+Added @aliases endpoint with GET/POST/DELETE
+[iulianpetchesi]

src/plone/restapi/services/aliases/add.py

@@ -0,0 +1,119 @@
+from plone.restapi.deserializer import json_body
+from plone.restapi.services import Service
+from zope.interface import alsoProvides
+from zope.interface import implementer
+from zope.publisher.interfaces import IPublishTraverse
+from zope.component import getUtility
+from plone.app.redirector.interfaces import IRedirectionStorage
+from Products.CMFPlone.controlpanel.browser.redirects import absolutize_path
+from zope.component import getMultiAdapter
+from zExceptions import BadRequest
+from DateTime import DateTime
+from plone.restapi import _
+import plone.protect.interfaces
+
+
+@implementer(IPublishTraverse)
+class AliasesPost(Service):
+    """Creates new aliases"""
+
+    def reply(self):
+        data = json_body(self.request)
+        storage = getUtility(IRedirectionStorage)
+        aliases = data.get("items", [])
+
+        if isinstance(aliases, str):
+            aliases = [
+                aliases,
+            ]
+
+        # Disable CSRF protection
+        if "IDisableCSRFProtection" in dir(plone.protect.interfaces):
+            alsoProvides(self.request, plone.protect.interfaces.IDisableCSRFProtection)
+
+        failed_aliases = []
+        for alias in aliases:
+            if isinstance(alias, dict):
+                alias = alias.get("path")
+
+            if alias.startswith("/"):
+                # Check navigation root
+                alias = self.edit_for_navigation_root(alias)
+            else:
+                failed_aliases.append(alias)
+                continue
+
+            alias, err = absolutize_path(alias, is_source=True)
+
+            if err:
+                failed_aliases.append(alias)
+                continue
+
+            storage.add(
+                alias,
+                "/".join(self.context.getPhysicalPath()),
+                manual=True,
+            )
+
+        if len(failed_aliases) > 0:
+            return {
+                "type": "error",
+                "failed": failed_aliases,
+            }
+
+        return self.reply_no_content()
+
+    def edit_for_navigation_root(self, alias):
+        # Check navigation root
+        pps = getMultiAdapter((self.context, self.request), name="plone_portal_state")
+        nav_url = pps.navigation_root_url()
+        portal_url = pps.portal_url()
+        if nav_url != portal_url:
+            # We are in a navigation root different from the portal root.
+            # Update the path accordingly, unless the user already did this.
+            extra = nav_url[len(portal_url) :]
+            if not alias.startswith(extra):
+                alias = f"{extra}{alias}"
+        # Finally, return the (possibly edited) redirection
+        return alias
+
+
+@implementer(IPublishTraverse)
+class AliasesRootPost(Service):
+    """Creates new aliases via controlpanel"""
+
+    def reply(self):
+        data = json_body(self.request)
+        storage = getUtility(IRedirectionStorage)
+        aliases = data.get("items", [])
+
+        # Disable CSRF protection
+        if "IDisableCSRFProtection" in dir(plone.protect.interfaces):
+            alsoProvides(self.request, plone.protect.interfaces.IDisableCSRFProtection)
+
+        for alias in aliases:
+            redirection = alias.get("path")
+            target = alias.get("redirect-to")
+            abs_redirection, err = absolutize_path(redirection, is_source=True)
+            abs_target, target_err = absolutize_path(target, is_source=False)
+
+            if err and target_err:
+                err = f"{err} {target_err}"
+            elif target_err:
+                err = target_err
+            else:
+                if abs_redirection == abs_target:
+                    err = _(
+                        "Alternative urls that point to themselves will cause"
+                        " an endless cycle of redirects."
+                    )
+            if err:
+                raise BadRequest(err)
+
+            date = alias.get("datetime", None)
+            if date:
+                date = DateTime(date)
+
+            storage.add(abs_redirection, abs_target, now=date, manual=True)
+
+        return self.reply_no_content()

src/plone/restapi/services/aliases/configure.zcml

@@ -0,0 +1,61 @@
+<configure
+    xmlns="http://namespaces.zope.org/zope"
+    xmlns:plone="http://namespaces.plone.org/plone"
+    >
+
+  <plone:service
+      method="GET"
+      accept="application/json,application/schema+json"
+      factory=".get.AliasesGet"
+      for="Products.CMFPlone.interfaces.IPloneSiteRoot"
+      permission="zope2.View"
+      name="@aliases"
+      />
+
+  <plone:service
+      method="GET"
+      accept="application/json,application/schema+json"
+      factory=".get.AliasesGet"
+      for="Products.CMFCore.interfaces.IContentish"
+      permission="zope2.View"
+      name="@aliases"
+      />
+
+  <plone:service
+      method="POST"
+      factory=".add.AliasesPost"
+      for="*"
+      permission="cmf.ModifyPortalContent"
+      name="@aliases"
+      />
+
+  <plone:service
+      method="POST"
+      factory=".add.AliasesRootPost"
+      for="Products.CMFPlone.interfaces.IPloneSiteRoot"
+      permission="cmf.ModifyPortalContent"
+      name="@aliases"
+      />
+
+  <plone:service
+      method="DELETE"
+      factory=".delete.AliasesDelete"
+      for="*"
+      permission="cmf.ModifyPortalContent"
+      name="@aliases"
+      />
+
+  <plone:service
+      method="DELETE"
+      factory=".delete.AliasesDelete"
+      for="Products.CMFPlone.interfaces.IPloneSiteRoot"
+      permission="cmf.ModifyPortalContent"
+      name="@aliases"
+      />
+
+  <adapter
+      factory=".get.Aliases"
+      name="aliases"
+      />
+
+</configure>

src/plone/restapi/services/aliases/delete.py

@@ -0,0 +1,51 @@
+from plone.restapi.deserializer import json_body
+from plone.restapi.services import Service
+from zope.interface import alsoProvides
+from zope.interface import implementer
+from zope.publisher.interfaces import IPublishTraverse
+from zope.component import getUtility
+from plone.app.redirector.interfaces import IRedirectionStorage
+from Products.CMFPlone.controlpanel.browser.redirects import absolutize_path
+from plone.restapi.services.aliases.get import deroot_path
+import plone.protect.interfaces
+
+
+@implementer(IPublishTraverse)
+class AliasesDelete(Service):
+    """Deletes an alias from object"""
+
+    def reply(self):
+        data = json_body(self.request)
+        storage = getUtility(IRedirectionStorage)
+        aliases = data.get("items", [])
+
+        if isinstance(aliases, str):
+            aliases = [
+                aliases,
+            ]
+
+        # Disable CSRF protection
+        if "IDisableCSRFProtection" in dir(plone.protect.interfaces):
+            alsoProvides(self.request, plone.protect.interfaces.IDisableCSRFProtection)
+
+        failed_aliases = []
+        for alias in aliases:
+            if isinstance(alias, dict):
+                alias = alias.get("path")
+
+            alias, _err = absolutize_path(alias, is_source=True)
+
+            try:
+                storage.remove(alias)
+            except KeyError:
+                alias = deroot_path(alias)
+                failed_aliases.append(alias)
+                continue
+
+        if len(failed_aliases) > 0:
+            return {
+                "type": "error",
+                "failed": failed_aliases,
+            }
+
+        return self.reply_no_content()