Modernise the Moodle LMS web service functionality.

This epic will collate issues related to the creation of a new Web Service infrastructure in Moodle.

Targetted at Moodle 4.4, this project epic seeks to replace the existing webservice infrastructure with a completely new approach utilising modern best practice.

This project seeks to create a new, standards-compliant, Web Service API for Moodle which puts focus on standardisation, growth, and discoverability.

New web services should be easy for developers to write, test, discover, and consume. Developers (and other entities) looking to integrate with Moodle’s existing web services should have a reduced “learning curve” and be able to self-discover the available functionality. The solution should be consistent with a RESTful design pattern.

Request handling should be performed in a standardised way, and responses should be standards-compliant (where appropriate). For example using standard HTTP verbs, request and response headers, response codes and standard formats like JSON (for response and request payloads).

Future changes and versioning of web service endpoints should be supported.

Authentication and Authorisation should be tightly integrated.

In summary, the high-level objectives of this project include:

• providing a modern Web Service API;
• supporting standardised error handling;
• allowing for future growth and change in response data;
• adding support for industry standard authentication mechanisms such as OAuth2;
• supporting discovery of available data; and
• providing a migration path from the old API to the new API over a long period of time
• easy and straightforward client implementation in Moodle LMS

Existing web services will continue to operate in parallel with the new design, and will be deprecated over time.

Technology selection

Protocol selection

Due to its simpler client-side implementation, broader support from integrated systems, and ease of maintenance, with predictable, resource-oriented URLs we feel that REST is the most suitable long-term solution for Moodle. Additionally, REST's alignment with current Moodle web services, support from tools like Postman, and documentation generation capabilities via OpenAPI and Swagger, provided a more seamless transition and familiarity.

We feel that these benefits outweigh the potential benefits of protocols such as GraphQL.

The lack of requirement for a specific client (unlike GraphQL) is also a key design consideration.

URI Design

The API should support future expansion of both technology, and version. For example it should be possible to indicate a future major version of the API via use of a new version in the URI, whilst still supporting the current version, or to an alternative to REST.

URIs will be composed of a base URI, and a URI suffix. An example of a base URI, including the technology (rest), and the API version (2) may be:

Base URI: https://example.com/api/rest/v2

This design proposes use of path-based services such that REST services are accessed by the URI, rather than a URL parameter.

Multiple levels of nesting will be supported, but encouraged to be kept to a minimum.

To interact with Posts within discussion entity with id 9403 with the mod_forum component:

https://example.com/api/rest/v2/mod_forum/discussions/9403/posts

Entity names must be plural.

The REST specification specifies use of a number of standard verbs and allocates meaning. We intends to abide by this specification and will make use of the standard HTTP verbs, for example:

GET - Fetch an entity or set of entities

• https://example.com/api/rest/v2/mod_forum/discussions
• https://example.com/api/rest/v2/mod_forum/discussions/123

HEAD - detect whether an entity exists

• https://example.com/api/rest/v2/mod_forum/discussions/123

POST - create a new entity

• https://example.com/api/rest/v2/mod_forum/discussions

PUT - update or create a new entity

• https://example.com/api/rest/v2/mod_forum/discussions/123

DELETE - remove an entity

• https://example.com/api/rest/v2/mod_forum/discussions/123

OPTIONS - fetch available verbs on the requested entity

• https://example.com/api/rest/v2/mod_forum/discussions

Routing

As a part of this change, we are looking at add support for a standardised Routing API, with support for Middleware, and utilising standard HTTP Request and Response interfaces in accordance with PSR-7.

Service descriptions

With the proposed new API we intend to make use of PHP Attributes to:

• compose the path of a route
• identify any accepted HTTP methods (verbs)
• describe all header, query, and path parameters
• describe response parameters

An example may look like:

#[route(

    path: '/preferences',

)]

class preferences {

    use \core\router\route_controller;

    #[route(

        path: '[/{preference}]',

        title: 'Fetch user preferences',

        description: 'Fetch one user preference, or all user preferences',

        pathtypes: [

            new \core\router\schema\parameters\path_parameter(

                name: 'preference',

                type: param::RAW,

            ),

        ],

        responses: [

            200 => new user_preferences_response(),

        ],

    )]

Validation of all request and response attributes (parameters and request body) will be performed by routing middleware.

Standards

Where relevant, we intend to adopt existing standards, including:

• PSR-7 - HTTP Message Interfaces
• PSR-15 - HTTP Server Handler and Middleware
• PSR-17 - HTTP Factories
• PSR-11 - Containers
• OpenAPI 3.1

Route attributes will automatically generate relevant documentation in the OpenAPI format, for consumption by an OpenAPI-compatible client or client generator.

Responses and Error handling

Responses will use the relevant HTTP status code with errors emitting useful and pertinent information.

Stack traces will only be included on errors when debugging modes are enabled.