@site and @navroot endpoints (#1465)

* documentation about the @site and @navroot endpoints

* remove descriptions

* @site and @navroot endpoint implementations

* tests

* black

* pretty

* documentation tests

* changelog

* Additional items in site endpoint

* whitespace

* black

* new values in @site endpoint

* more tests

* polish docs

* Update docs/source/navroot.md

Co-authored-by: Steve Piercy <web@stevepiercy.com>

* Update docs/source/navroot.md

Co-authored-by: Steve Piercy <web@stevepiercy.com>

* Update docs/source/navroot.md

Co-authored-by: Steve Piercy <web@stevepiercy.com>

* Update docs/source/navroot.md

Co-authored-by: Steve Piercy <web@stevepiercy.com>

* Update docs/source/navroot.md

Co-authored-by: Steve Piercy <web@stevepiercy.com>

* add term to glossary

* add description

* title

* Update docs/source/site.md

Co-authored-by: Steve Piercy <web@stevepiercy.com>

* conbine sentences

* Update docs/source/glossary.md

Co-authored-by: Katja Süss <k.suess@rohberg.ch>

* Update translated_messages_addons.resp

* add examples using expansion

* Update docs/source/navroot.md

* Update docs/source/navroot.md

* Update docs/source/navroot.md

* Update docs/source/navroot.md

* Update docs/source/navroot.md

* Update docs/source/navroot.md

* Update docs/source/navroot.md

Co-authored-by: Steve Piercy <web@stevepiercy.com>

* Update docs/source/glossary.md

Co-authored-by: Steve Piercy <web@stevepiercy.com>

* more documentation on the @navroot endpoint

* more documentation on the @navroot endpoint

* whitespace

* black

* Update docs/source/navroot.md

Co-authored-by: Steve Piercy <web@stevepiercy.com>

* Update docs/source/navroot.md

Co-authored-by: Steve Piercy <web@stevepiercy.com>

* Update docs/source/navroot.md

Co-authored-by: Steve Piercy <web@stevepiercy.com>

* Update docs/source/navroot.md

Co-authored-by: Steve Piercy <web@stevepiercy.com>

* Update docs/source/navroot.md

Co-authored-by: Steve Piercy <web@stevepiercy.com>

* Update docs/source/navroot.md

Co-authored-by: Steve Piercy <web@stevepiercy.com>

* fix tests

* Update translated_messages_addons.resp

* Update workingcopy_baseline_get.resp

* Reorganize navigation (#1490)

* Move contributing stuff around

* Add usage directory, move files, adjust paths

* Reorganize endpoints, adjust paths

* Fix paths for usage/* files

* Merge content-negotiation.md into introduction.md and clean up English grammar and MyST syntax

* Move actions so that it sorts with its title "Portal Actions"

* Rename page from "Plone Content" to "Content Types"

* Add towncrier news item for documentation change.

* Resolve merge conflicts with master

* reorganize docs

* register the static UUID generator when preparing the Plone site

* imp

* register the static UUID generator globally

* remove unused imports

* remove unneeded code, language configuration is already done in layer setup

* rework @site and @navroot tests to have them in already existing testcases

* setup the static uuid generator

* regenerate http resp files for tests because of the changes in UUID generation

* remove unneeded

* delete

* polish docs

* polish docs

* restore old configuration

* restore old UUIDs

* remove unneeded imports

* remove unneeded imports

* black

* change files

* change

* Update translated_messages_addons.resp

* update tests

* add UID to the Plone site root

* rename exposed properties to match registry record names

* black

* Fixed news snippet extension.

[ci skip]

* Preparing release 8.35.3

[ci skip]

* Back to development: 8.35.4

[ci skip]

* register the expander for navroot and update documentation test results

* configure @site endpoint as an expandable

* black

* Fix ReST on navroot.md

* Update docs/source/endpoints/navroot.md

Co-authored-by: Steve Piercy <web@stevepiercy.com>

* Update docs/source/endpoints/navroot.md

Co-authored-by: Steve Piercy <web@stevepiercy.com>

* Update docs/source/endpoints/navroot.md

Co-authored-by: Steve Piercy <web@stevepiercy.com>

* Update docs/source/endpoints/navroot.md

Co-authored-by: Steve Piercy <web@stevepiercy.com>

* Update docs/source/endpoints/navroot.md

Co-authored-by: Steve Piercy <web@stevepiercy.com>

* Update docs/source/endpoints/navroot.md

Co-authored-by: Steve Piercy <web@stevepiercy.com>

* Update docs/source/endpoints/navroot.md

Co-authored-by: Steve Piercy <web@stevepiercy.com>

* Update docs/source/endpoints/navroot.md

Co-authored-by: Steve Piercy <web@stevepiercy.com>

* Update docs/source/endpoints/navroot.md

Co-authored-by: Steve Piercy <web@stevepiercy.com>

* Update docs/source/endpoints/navroot.md

Co-authored-by: Steve Piercy <web@stevepiercy.com>

* Update docs/source/endpoints/navroot.md

Co-authored-by: Steve Piercy <web@stevepiercy.com>

* Update docs/source/endpoints/navroot.md

Co-authored-by: Steve Piercy <web@stevepiercy.com>

* Update docs/source/endpoints/navroot.md

Co-authored-by: Steve Piercy <web@stevepiercy.com>

* Update docs/source/endpoints/navroot.md

Co-authored-by: Steve Piercy <web@stevepiercy.com>

* Update docs/source/endpoints/site.md

Co-authored-by: Steve Piercy <web@stevepiercy.com>

* Update docs/source/glossary.md

Co-authored-by: Steve Piercy <web@stevepiercy.com>

* remove unneeded term

* remove misleading sentence

* fix path

* include the navroot serialized in the @navroot call

* run black

* update docs

* update docs tests

* manually set uids for LRF objects

* black

* Update docs/source/endpoints/navroot.md

Co-authored-by: David Glick <david@glicksoftware.com>

* Update docs/source/endpoints/navroot.md

Co-authored-by: David Glick <david@glicksoftware.com>

* Update docs/source/endpoints/navroot.md

Co-authored-by: David Glick <david@glicksoftware.com>

* Update news/1464.feature

Co-authored-by: David Glick <david@glicksoftware.com>

* Update docs/source/endpoints/navroot.md

Co-authored-by: David Glick <david@glicksoftware.com>

* Update docs/source/endpoints/navroot.md

Co-authored-by: David Glick <david@glicksoftware.com>

* Update docs/source/endpoints/navroot.md

Co-authored-by: David Glick <david@glicksoftware.com>

* remove the expandability of @site

---------

Co-authored-by: Steve Piercy <web@stevepiercy.com>
Co-authored-by: Katja Süss <k.suess@rohberg.ch>
Co-authored-by: Timo Stollenwerk <tisto@users.noreply.github.com>
Co-authored-by: Jens W. Klein <jk@kleinundpartner.at>
Co-authored-by: Andrei Grigore <44702393+andreiggr@users.noreply.github.com>
Co-authored-by: Maurits van Rees <maurits@vanrees.org>
Co-authored-by: Timo Stollenwerk <stollenwerk@kitconcept.com>
Co-authored-by: Alin Voinea <contact@avoinea.com>
Co-authored-by: David Glick <david@glicksoftware.com>

docs/source/endpoints/index.md

@@ -35,6 +35,7 @@ history
 linkintegrity
 locking
 navigation
+navroot
 actions
 portrait
 principals
@@ -44,6 +45,7 @@ registry
 relations
 roles
 searching
+site
 system
 tiles
 transactions

docs/source/endpoints/navroot.md

@@ -0,0 +1,158 @@
+---
+html_meta:
+  "description": "Navigation root is a concept that provides a way to root catalog queries, searches, and breadcrumbs in Plone."
+  "property=og:description": "Navigation root is a concept that provides a way to root catalog queries, searches, and breadcrumbs in Plone."
+  "property=og:title": "Navigation Root"
+  "keywords": "Plone, plone.restapi, REST, API, site, navigation root"
+---
+
+(navigation-root-label)=
+
+# Navigation root
+
+Plone has a concept called {term}`navigation root` which provides a way to root catalog queries, searches, breadcrumbs, and so on in a given section of the site.
+This feature is useful when working with subsites or multilingual sites, because it allows the site manager to restrict searches or navigation queries to a specific location in the site.
+
+This navigation root information is different depending on the context of the request.
+For instance, in a default multilingual site when browsing the contents inside a language folder such as `www.domain.com/en`, the context is `en` and its navigation root will be `/en/`.
+In a non-multilingual site, the context is the root of the site such as `www.domain.com` and the navigation root will be `/`.
+
+To get the information about the navigation root, the REST API has a `@navroot` contextual endpoint.
+For instance, send a `GET` request to the `@navroot` endpoint at the root of the site:
+
+```{eval-rst}
+..  http:example:: curl httpie python-requests
+    :request: ../../../src/plone/restapi/tests/http-examples/navroot_standard_site_get.req
+```
+
+The response will contain the navigation root information for the site:
+
+```{literalinclude} ../../../src/plone/restapi/tests/http-examples/navroot_standard_site_get.resp
+:language: http
+```
+
+If you request the `@navroot` of a given content item in the site:
+
+```{eval-rst}
+..  http:example:: curl httpie python-requests
+    :request: ../../../src/plone/restapi/tests/http-examples/navroot_standard_site_content_get.req
+```
+
+The response will contain the navigation root information in the context of that content item:
+
+```{literalinclude} ../../../src/plone/restapi/tests/http-examples/navroot_standard_site_content_get.resp
+:language: http
+```
+
+In a multilingual site, the root of the site will work as usual:
+
+```{eval-rst}
+..  http:example:: curl httpie python-requests
+    :request: ../../../src/plone/restapi/tests/http-examples/navroot_site_get.req
+```
+
+The response will contain the navigation root information of the root of the site:
+
+```{literalinclude} ../../../src/plone/restapi/tests/http-examples/navroot_site_get.resp
+:language: http
+```
+
+In a multilingual site where the language folder is the navigation root, the response has the language folder information:
+
+```{eval-rst}
+..  http:example:: curl httpie python-requests
+    :request: ../../../src/plone/restapi/tests/http-examples/navroot_lang_folder_get.req
+```
+
+The response will contain the navigation root information for the language folder:
+
+```{literalinclude} ../../../src/plone/restapi/tests/http-examples/navroot_lang_folder_get.resp
+:language: http
+```
+
+In a multilingual site, if the navigation root is requested for content inside a language folder:
+
+```{eval-rst}
+..  http:example:: curl httpie python-requests
+    :request: ../../../src/plone/restapi/tests/http-examples/navroot_lang_content_get.req
+```
+
+The response has the language folder information as a navigation root:
+
+```{literalinclude} ../../../src/plone/restapi/tests/http-examples/navroot_lang_content_get.resp
+:language: http
+```
+
+(navigation-root-expansion-label)=
+
+## Expansion
+
+This endpoint can be used with the {doc}`expansion` mechanism which allows getting more information about a content item in one query, avoiding unnecessary requests.
+
+If a simple `GET` request is made on the content item, a new entry will be shown on the `@components` entry with the URL of the `@navroot` endpoint.
+
+In a standard site when querying the site root:
+
+```{eval-rst}
+..  http:example:: curl httpie python-requests
+    :request: ../../../src/plone/restapi/tests/http-examples/navroot_standard_site_get_expansion.req
+```
+
+The response will contain information of the site root with the navigation expanded:
+
+```{literalinclude} ../../../src/plone/restapi/tests/http-examples/navroot_standard_site_get_expansion.resp
+:language: http
+```
+
+When querying a content item inside the root:
+
+```{eval-rst}
+..  http:example:: curl httpie python-requests
+    :request: ../../../src/plone/restapi/tests/http-examples/navroot_standard_site_content_get_expansion.req
+```
+
+The response will contain the information of that content item with its navigation root information expanded:
+
+```{literalinclude} ../../../src/plone/restapi/tests/http-examples/navroot_standard_site_content_get_expansion.resp
+:language: http
+```
+
+In a multilingual site, it works the same.
+Use the request:
+
+```{eval-rst}
+..  http:example:: curl httpie python-requests
+    :request: ../../../src/plone/restapi/tests/http-examples/site_get_expand_navroot.req
+```
+
+And the response will contain the navigation root information pointing to the root of the site:
+
+```{literalinclude} ../../../src/plone/restapi/tests/http-examples/site_get_expand_navroot.resp
+:language: http
+```
+
+It will also work with language root folders that are navigation roots:
+
+```{eval-rst}
+..  http:example:: curl httpie python-requests
+    :request: ../../../src/plone/restapi/tests/http-examples/site_get_expand_lang_folder.req
+```
+
+The response will contain the navigation root information expanded:
+
+```{literalinclude} ../../../src/plone/restapi/tests/http-examples/site_get_expand_lang_folder.resp
+:language: http
+```
+
+And also for content inside the language root folders:
+
+```{eval-rst}
+.. http:example:: curl httpie python-requests
+   :request: ../../../src/plone/restapi/tests/http-examples/site_get_expand_lang_folder_content.req
+```
+
+The response will include the expanded information pointing to the language root:
+
+```{literalinclude} ../../../src/plone/restapi/tests/http-examples/site_get_expand_lang_folder_content.resp
+:language: http
+```

docs/source/endpoints/site.md

@@ -0,0 +1,25 @@
+---
+html_meta:
+  "description": "Site endpoint for Plone REST API"
+  "property=og:title": "Site endpoint for Plone REST API"
+  "property=og:description": "Site endpoint for Plone REST API"
+  "keywords": "Plone, plone.restapi, REST, API, site, navigation root"
+---
+
+# Site
+
+The `@site` endpoint provides general site-wide information, such as the site title, logo, and other information.
+It uses the `zope2.View` permission, which requires appropriate authorization.
+
+Send a `GET` request to the `@site` endpoint:
+
+```{eval-rst}
+..  http:example:: curl httpie python-requests
+    :request: ../../../src/plone/restapi/tests/http-examples/site_get.req
+```
+
+The response will contain the site information:
+
+```{literalinclude} ../../../src/plone/restapi/tests/http-examples/site_get.resp
+:language: http
+```

docs/source/glossary.md

@@ -53,11 +53,15 @@ Authentication Method
 
 Basic Auth
     A simple {term}`Authentication Method` referenced in the {term}`Authorization Header` that needs to be provided by the server.
-
+    
 content rule
     A content rule will automatically perform an action when a certain event, known as a {term}`trigger`, takes place.
 
 trigger
     A trigger is an event in Plone that causes the execution of defined actions.
     Example triggers include object modified, user logged in, and workflow state changed.
+
+navigation root
+    An object marked as a navigation root provides a way to root catalog queries, searches, breadcrumbs, and so on, into that object.
+
 ```

docs/source/index.md

@@ -31,15 +31,13 @@ contributing/index
 .. include:: ../../README.rst
 ```
 
-
 ## Appendix and Glossary
 
 ```{toctree}
 http-status-codes
 /glossary
 ```
 
-
 ## Index
 
 - {ref}`genindex`

news/1464.feature

@@ -0,0 +1 @@
+Added `@site` and `@navroot` endpoints. @erral 

src/plone/restapi/services/configure.zcml

@@ -25,6 +25,7 @@
   <include package=".history" />
   <include package=".linkintegrity" />
   <include package=".locking" />
+  <include package=".navroot" />
   <include package=".principals" />
   <include package=".querysources" />
   <include package=".querystring" />
@@ -33,6 +34,7 @@
   <include package=".relations" />
   <include package=".roles" />
   <include package=".search" />
+  <include package=".site" />
   <include package=".system" />
   <include package=".sources" />
   <include package=".transactions" />

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

@@ -0,0 +1,23 @@
+<configure
+    xmlns="http://namespaces.zope.org/zope"
+    xmlns:cache="http://namespaces.zope.org/cache"
+    xmlns:plone="http://namespaces.plone.org/plone"
+    xmlns:zcml="http://namespaces.zope.org/zcml"
+    >
+
+  <plone:service
+      method="GET"
+      factory=".get.NavrootGet"
+      for="zope.interface.Interface"
+      permission="zope2.View"
+      name="@navroot"
+      />
+
+
+  <adapter
+      factory=".get.Navroot"
+      name="navroot"
+      />
+
+
+</configure>

src/plone/restapi/services/navroot/get.py

@@ -0,0 +1,39 @@
+# -*- coding: utf-8 -*-
+from plone.restapi.interfaces import IExpandableElement, ISerializeToJson
+from plone.restapi.services import Service
+from zope.component import adapter
+from zope.component import getMultiAdapter
+from zope.interface import implementer
+from zope.interface import Interface
+
+
+@implementer(IExpandableElement)
+@adapter(Interface, Interface)
+class Navroot:
+    def __init__(self, context, request):
+        self.context = context
+        self.request = request
+
+    def __call__(self, expand=False):
+        result = {"navroot": {"@id": f"{self.context.absolute_url()}/@navroot"}}
+        if not expand:
+            return result
+
+        portal_state = getMultiAdapter(
+            (self.context, self.request), name="plone_portal_state"
+        )
+        # We need to unset expansion here, otherwise we get infinite recursion
+        self.request.form["expand"] = ""
+
+        result["navroot"]["navroot"] = getMultiAdapter(
+            (portal_state.navigation_root(), self.request),
+            ISerializeToJson,
+        )()
+
+        return result
+
+
+class NavrootGet(Service):
+    def reply(self):
+        navroot = Navroot(self.context, self.request)
+        return navroot(expand=True)["navroot"]

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

@@ -0,0 +1,14 @@
+<configure
+    xmlns="http://namespaces.zope.org/zope"
+    xmlns:plone="http://namespaces.plone.org/plone"
+    >
+
+  <plone:service
+      method="GET"
+      factory=".get.SiteGet"
+      for="Products.CMFPlone.interfaces.IPloneSiteRoot"
+      permission="zope2.View"
+      name="@site"
+      />
+
+</configure>

src/plone/restapi/services/site/get.py

@@ -0,0 +1,50 @@
+# -*- coding: utf-8 -*-
+from plone.registry.interfaces import IRegistry
+from plone.restapi.interfaces import IExpandableElement
+from plone.restapi.services import Service
+from Products.CMFPlone.interfaces import IImagingSchema
+from Products.CMFPlone.interfaces import ISiteSchema
+from Products.CMFPlone.utils import getSiteLogo
+from zope.component import adapter
+from zope.component import getMultiAdapter
+from zope.component import getUtility
+from zope.interface import implementer
+from zope.interface import Interface
+
+
+@implementer(IExpandableElement)
+@adapter(Interface, Interface)
+class Site:
+    def __init__(self, context, request):
+        self.context = context
+        self.request = request
+
+    def __call__(self, expand=False):
+        result = {"site": {"@id": f"{self.context.absolute_url()}/@site"}}
+        if not expand:
+            return result
+
+        portal_state = getMultiAdapter(
+            (self.context, self.request), name="plone_portal_state"
+        )
+        registry = getUtility(IRegistry)
+        site_settings = registry.forInterface(ISiteSchema, prefix="plone", check=False)
+        image_settings = registry.forInterface(
+            IImagingSchema, prefix="plone", check=False
+        )
+        result["site"].update(
+            {
+                "plone.site_title": portal_state.portal_title(),
+                "plone.site_logo": site_settings.site_logo and getSiteLogo() or None,
+                "plone.robots_txt": site_settings.robots_txt,
+                "plone.allowed_sizes": image_settings.allowed_sizes,
+            }
+        )
+
+        return result
+
+
+class SiteGet(Service):
+    def reply(self):
+        site = Site(self.context, self.request)
+        return site(expand=True)["site"]