Skip to main content

Routing Policies

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 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​

Where a component is present in the URL, the value is automatically determined from the location of the class defining the route.

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:

/rest/api/v2/course/<courseid>
/course/<courseid>/view

The following are examples of a non-default entity:

/rest/api/v2/core/templates/<theme>/<templateName>
/rest/api/v2/core/strings/<language>/<stringComponent>/<stringIdentifier>
Default and non-default entities

The use of both a default entity and a non-default entity is not officially supported.

Singular or Plural

Where present, entities should always be in the plural form.

REST API Route Paths​

All REST paths follow the following format:

/rest/api/v2/<component>/<path>
tip

The standard rules 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 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