From 0acf6eece13e26616aec7e5544f046552e820bb2 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Tue, 7 Feb 2023 13:07:33 -0500 Subject: [PATCH 1/2] Document about cross-site request --- docs/user/api/cross-site-requests.rst | 30 +++++++++++++++++++++++++++ docs/user/api/index.rst | 1 + docs/user/api/v2.rst | 1 - 3 files changed, 31 insertions(+), 1 deletion(-) create mode 100644 docs/user/api/cross-site-requests.rst diff --git a/docs/user/api/cross-site-requests.rst b/docs/user/api/cross-site-requests.rst new file mode 100644 index 00000000000..9991bda1157 --- /dev/null +++ b/docs/user/api/cross-site-requests.rst @@ -0,0 +1,30 @@ +Cross-site requests +=================== + +Cross site requests are allowed for the following endpoints: + +- :ref:`/api/v2/footer_html/ ` +- :ref:`/api/v2/search/ ` +- :ref:`/api/v2/embed/ ` +- :ref:`/api/v2/sustainability/ ` +- :ref:`/api/v3/embed/ ` + +Except for the sustainability API, all of the above endpoints +don't allow you to pass credentials in cross-site requests. +This means you can make use of those APIs to get information from public versions only. + +Cookies +------- + +For |org_brand| our session cookies have the ``SameSite`` attribute set to ``None``, +this means they can be sent in cross site requests. +This is needed for our sustainability API only, +to not show ads if the current user is a :ref:`Gold User `. +All resources in |org_brand| are public, you don't need to pass cookies to make use +of our allowed APIs from other sites. + +For |com_brand| our session cookies have the ``SameSite`` attribute set to ``Lax``, +this means they can't be included in cross site requests. +If you need to have access to versions that the current user has permissions over, +you can make use of our proxied APIs, they can be accessed from docs domains with the `/_/` prefix. +For example, you can make use of our search API from `/_/api/v2/search/`. diff --git a/docs/user/api/index.rst b/docs/user/api/index.rst index 99a0878de4b..bb2ea66d1d6 100644 --- a/docs/user/api/index.rst +++ b/docs/user/api/index.rst @@ -12,3 +12,4 @@ from Read the Docs. v3 v2 + cross-site-requests diff --git a/docs/user/api/v2.rst b/docs/user/api/v2.rst index 05f71d8af45..367b4224d96 100644 --- a/docs/user/api/v2.rst +++ b/docs/user/api/v2.rst @@ -408,7 +408,6 @@ There are some undocumented endpoints in the API. These should not be used and could change at any time. These include: -* The search API (``/api/v2/search/``) * Endpoints for returning footer and version data to be injected into docs. (``/api/v2/footer_html``) * Endpoints used for advertising (``/api/v2/sustainability/``) From a44a87f78c7b2774f7ad99026fd13b7c209b76bd Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Thu, 9 Feb 2023 17:06:10 -0500 Subject: [PATCH 2/2] Updates from review --- docs/user/api/cross-site-requests.rst | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/user/api/cross-site-requests.rst b/docs/user/api/cross-site-requests.rst index 9991bda1157..2e1d38a1ed0 100644 --- a/docs/user/api/cross-site-requests.rst +++ b/docs/user/api/cross-site-requests.rst @@ -11,20 +11,26 @@ Cross site requests are allowed for the following endpoints: Except for the sustainability API, all of the above endpoints don't allow you to pass credentials in cross-site requests. -This means you can make use of those APIs to get information from public versions only. +In other words, these API endpoints allow you to access **public information only**. + +On a technical level, this is achieved by implementing the CORS_ standard, +which is supported by all major browsers. +We implement it such way that it strictly match the intention of the API endpoint. + +.. _CORS: https://en.wikipedia.org/wiki/Cross-origin_resource_sharing Cookies ------- -For |org_brand| our session cookies have the ``SameSite`` attribute set to ``None``, +On |org_brand|, our session cookies have the ``SameSite`` attribute set to ``None``, this means they can be sent in cross site requests. This is needed for our sustainability API only, to not show ads if the current user is a :ref:`Gold User `. All resources in |org_brand| are public, you don't need to pass cookies to make use of our allowed APIs from other sites. -For |com_brand| our session cookies have the ``SameSite`` attribute set to ``Lax``, -this means they can't be included in cross site requests. +On |com_brand|, our session cookies have the ``SameSite`` attribute set to ``Lax``. +This means that browsers will not include them in cross site requests. If you need to have access to versions that the current user has permissions over, you can make use of our proxied APIs, they can be accessed from docs domains with the `/_/` prefix. For example, you can make use of our search API from `/_/api/v2/search/`.