backport #1465: @site and @navroot endpoints (#1702)

* backport #1465: @site and @navroot endpoints

* fix

* black

* fix

* remove duplicated import

* fixes

* black

* f-strings are not available in python2

* adapt for Plone 4.3

* adapt for Plone 4.3

* adapt for Plone 4.3

* adapt for Plone 4.3

* skip multilingual tests when not installed

* skip multilingual tests when not installed

* remove unneeded

* make tests for Plone 5

* make tests for Plone 5

* make tests for Plone 5

---------

Co-authored-by: David Glick <[email protected]>

docs/source/endpoints/index.md

@@ -0,0 +1,61 @@
+---
+myst:
+  html_meta:
+    "description": "Usage of the Plone REST API."
+    "property=og:description": "Usage of the Plone REST API."
+    "property=og:title": "Usage of the Plone REST API"
+    "keywords": "Plone, plone.restapi, REST, API, Usage"
+---
+
+(restapi-endpoints)=
+
+# Endpoints
+
+This part of the documentation explains the endpoints of Plone REST API.
+
+```{toctree}
+:caption: Table of Contents
+:maxdepth: 2
+
+addons
+aliases
+breadcrumbs
+comments
+content-types
+content-rules
+contextnavigation
+controlpanels
+copymove
+database
+email-notification
+email-send
+expansion
+groups
+history
+linkintegrity
+locking
+navigation
+navroot
+actions
+portrait
+principals
+querystring
+querystringsearch
+registry
+relations
+roles
+searching
+site
+system
+tiles
+transactions
+translations
+tusupload
+types
+upgrade
+users
+userschema
+vocabularies
+workflow
+workingcopy
+```

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

@@ -0,0 +1,67 @@
+---
+myst:
+  html_meta:
+    "description": "plone.restapi Glossary"
+    "property=og:description": "plone.restapi Glossary"
+    "property=og:title": "Glossary"
+    "keywords": "Plone, plone.restapi, REST, API, Glossary"
+---
+
+# Glossary
+
+```{glossary}
+:sorted: true
+
+REST
+    REST stands for [Representational State Transfer](https://en.wikipedia.org/wiki/Representational_state_transfer). It is a software architectural principle to create loosely coupled web APIs.
+
+workflow
+    A concept in Plone (and other CMS's) whereby a content object can be in a number of states (private, public, etcetera) and uses transitions to change between them (e.g. "publish", "approve", "reject", "retract"). See the [Plone docs on Workflow](https://5.docs.plone.org/working-with-content/collaboration-and-workflow/)
+
+HTTP-Request
+HTTP Request
+Request
+Requests
+    The initial action performed by a web client to communicate with a server. The {term}`Request` is usually followed by a {term}`Response` by the server, either synchronous or asynchronous (which is more complex to handle on the user side)
+
+HTTP-Response
+HTTP Response
+Response
+    Answer of or action by the server that is executed or send to the client after the {term}`Request` is processed.
+
+HTTP-Header
+HTTP Header
+Header
+    The part of the communication of the client with the server that provides the initialisation of the communication of a {term}`Request`.
+
+HTTP-Verb
+HTTP Verb
+Verb
+    One of the basic actions that can be requested to be executed by the server (on an object) based on the {term}`Request`.
+
+Object URL
+    The target object of the {term}`Request`
+
+Authorization Header
+    Part of the {term}`Request` that is responsible for the authentication related to the right user or service to ask for a {term}`Response`.
+
+Accept Header
+    Part of the {term}`Request` that is responsible to define the expected type of data to be accepted by the client in the {term}`Response`.
+
+Authentication Method
+    Access restriction provided by the connection chain to the server exposed to the client.
+
+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

@@ -0,0 +1,43 @@
+---
+myst:
+  html_meta:
+    "description": "A RESTful API for Plone."
+    "property=og:description": "A RESTful API for Plone."
+    "property=og:title": "REST API"
+    "keywords": "Plone, plone.restapi, REST, API"
+---
+
+% plone.restapi documentation master file, created by
+% sphinx-quickstart on Mon Apr 28 13:04:12 2014.
+% You can adapt this file completely to your liking, but it should at least
+% contain the root `toctree` directive.
+
+# REST API
+
+A RESTful API for Plone.
+
+```{toctree}
+:caption: Table of Contents
+:maxdepth: 2
+
+introduction
+usage/index
+endpoints/index
+upgrade-guide
+contributing/index
+```
+
+```{eval-rst}
+.. 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

@@ -23,13 +23,15 @@
   <include package=".contextnavigation" />
   <include package=".history" />
   <include package=".locking" />
+  <include package=".navroot" />
   <include package=".principals" />
   <include package=".querysources" />
   <include package=".querystring" />
   <include package=".querystringsearch" />
   <include package=".registry" />
   <include package=".roles" />
   <include package=".search" />
+  <include package=".site" />
   <include package=".system" />
   <include package=".sources" />
   <include package=".types" />