Add comprehensive documentation for URL namespacing

docs/backend_architecture/content/api_endpoints.rst

@@ -1,6 +1,30 @@
 API endpoints
 -------------
 
+URL Namespacing
+~~~~~~~~~~~~~~~
+
+Kolibri uses a consistent URL namespacing pattern throughout the codebase. All URLs follow the format:
+
+    >>> kolibri:<plugin_module>:<url_name>
+
+Where ``<plugin_module>`` is either ``core`` for core Kolibri functionality (a special case, as core is not actually in a plugin module), or the full plugin module path (e.g., ``kolibri.plugins.coach``) for plugins.
+
+For example:
+
+    >>> kolibri:core:session_list
+    >>> kolibri:core:session_detail
+    >>> kolibri:core:usernameavailable
+    >>> kolibri:kolibri.plugins.coach:lessonreport_list
+    >>> kolibri:kolibri.plugins.coach:lessonreport_detail
+
+This namespacing is used both in Django backend URL configuration and in JavaScript frontend code.
+
+For comprehensive information about URL namespacing, including how to define and use URLs in both backend and frontend code, see the :doc:`/howtos/working_with_urls_and_api_endpoints` guide.
+
+Example Endpoints
+~~~~~~~~~~~~~~~~~
+
 request specific content:
 
     >>> localhost:8000/api/content/<channel_id>/contentnode/<content_id>

docs/frontend_architecture/core.rst

@@ -79,7 +79,29 @@ Bootstrapped data
 
 The ``kolibriCoreAppGlobal`` object is also used to bootstrap data into the JS app, rather than making unnecessary API requests.
 
-For example, we currently embellish the ``kolibriCoreAppGlobal`` object with a ``urls`` object. This is defined by `Django JS Reverse <https://github.com/ierror/django-js-reverse>`__ and exposes Django URLs on the client side. This will primarily be used for accessing API Urls for synchronizing with the REST API. See the Django JS Reverse documentation for details on invoking the Url.
+For example, we currently embellish the ``kolibriCoreAppGlobal`` object with a ``urls`` object. This is defined by `Django JS Reverse <https://github.com/ierror/django-js-reverse>`__ and exposes Django URLs on the client side. This will primarily be used for accessing API Urls for synchronizing with the REST API.
+
+URLs and API Endpoints
+~~~~~~~~~~~~~~~~~~~~~~
+
+Kolibri uses a consistent URL namespacing pattern (e.g., ``kolibri:core:session_list``) that bridges Django's backend URL system with JavaScript frontend code. URLs can be accessed in JavaScript via the ``urls`` object:
+
+.. code-block:: javascript
+
+  import urls from 'kolibri/urls';
+  import client from 'kolibri/client';
+
+  // Call a list endpoint
+  const response = await client({
+    url: urls['kolibri:core:session_list'](),
+  });
+
+  // Call a detail endpoint with a parameter
+  const response = await client({
+    url: urls['kolibri:core:session_detail'](sessionId),
+  });
+
+For comprehensive information about URL namespacing, including how to define URLs in Django and use them in JavaScript, see the :doc:`/howtos/working_with_urls_and_api_endpoints` guide.
 
 Additional functionality
 ------------------------

docs/howtos/index.rst

@@ -16,3 +16,4 @@ These guides are step by step guides for common tasks in getting started and wor
   another_kolibri_instance
   development_with_kds
   preview_on_mobile
+  working_with_urls_and_api_endpoints