[docs] Add basic rules for routes

Author: andrewnicols

general/development/policies/routing/index.md

@@ -0,0 +1,155 @@
+---
+title: Routing Policies
+tags:
+  - Processes
+  - Core development
+  - Policy
+  - Routing
+  - Pages
+---
+
+This document describes the policies for route naming in Moodle.
+
+Routes are a powerful feature introduced in Moodle 4.5, and further extended in Moodle 5.0 which allow parts of Moodle, including plugins, to generate content without an explicit PHP endpoint file directly hit by users.
+
+See the [Routing system documentation](/docs/apis/subsystems/routing/index) for further information.
+
+Routes are currently used in the following places:
+
+- The REST API
+- End user content (pages)
+- Shims to redirect legacy locations to new pages (shims)
+
+Part of the URL used to access these pages is automatically generated by the component that the route is a part of, but the remaining part is generated by the developer.
+
+To ensure consistency across Moodle, and to mitigate the risk of route shadowing, Moodle follows some rules for route paths.
+
+Routes are typically comprised of:
+
+- the component prefix
+- an _entity_ type, for example `course`
+- an entity _identifier_, for example `948`
+- an _action_ on that entity, for example `view`
+
+Some of these parts may not be required, depending on the component and route type.
+
+## The Component {#component-naming}
+
+Where a component is present in the URL, the value is automatically determined from the location of the class defining the route.
+
+:::tip Component Appearance
+
+Where the component is a plugin, the full Frankenstyle Plugin Name is used, for example `mod_assign`.
+
+Where the component is a core subsystem such as `core_course` then the `core_` prefix is removed, for example `course`.
+
+:::
+
+## Entity types
+
+In many cases the component will be the entity, for example in the `core_course` component, the primary entity is the course. This is referred to as the _default_ entity.
+
+The following are examples of a default entity:
+
+``` title="The core_course subsystem has a default entity of 'course'"
+/rest/api/v2/course/<courseid>
+/course/<courseid>/view
+```
+
+The following are examples of a non-default entity:
+
+``` title="The core subsystem does not have any default entity"
+/rest/api/v2/core/templates/<theme>/<templateName>
+/rest/api/v2/core/strings/<language>/<stringComponent>/<stringIdentifier>
+```
+
+:::danger Default and non-default entities
+
+The use of both a _default_ entity _and_ a non-default entity is not officially supported.
+
+:::
+
+:::tip Singular or Plural
+
+Where present, entities should always be in the plural form.
+
+:::
+
+## REST API Route Paths {#rest-route-paths}
+
+All REST paths follow the following format:
+
+```
+/rest/api/v2/<component>/<path>
+```
+
+:::tip
+
+The [standard rules](#component-naming) for `component` formatting apply.
+
+:::
+
+### Action verbs on the REST API
+
+In most cases the REST API will make use of different HTTP Methods to dictate the relevant actions, for example:
+
+- `GET` to fetch data
+- `POST` - create data
+- `DELETE` to delete data
+
+Therefore the use of action verbs in REST API paths is strongly discouraged.
+
+### Sub-entities on the REST API
+
+In many cases an entity may have related child entities, or _sub-entities_. These should be placed after the primary or default entity's identifier, for example:
+
+```
+/rest/api/v2/course/<courseid>/section/<sectionid>
+```
+
+## Page Route Paths
+
+Moodle 5.0 adds support for page routes. Page routes allow a standard Moodle page to be served without the user visiting a PHP page explicitly created for that purpose.
+
+Page routes make use of the Routing engine to manage their complete end-to-end workflow.
+
+All Page routes follow the following format:
+
+```
+/<component>/<path>
+```
+
+:::tip
+
+The [standard rules](#component-naming) for `component` formatting apply.
+
+:::
+
+### Action verbs on Page Routes
+
+In the case of Page Routes, it is not possible to use HTTP methods. Instead an action verb should be specified.
+
+:::tip
+
+The action should be specified _after_ the identifier, for example:
+
+```
+/course/<identifier>/<action>
+```
+
+:::
+
+Action verbs should be single, simple, words and clearly identify the purpose of that action, for example:
+
+- `view`
+- `edit`
+- `manage`
+- `delete`
+
+### Sub-entities on Page Routes
+
+In many cases an entity may have related child entities. These should be placed after the identifier of the primary entity, for example:
+
+```
+/course/<courseid>/capabilities
+```