Background

Gone are the days of single monolithic files and classes.

Please, let us move to one web service, and one class, per file.

See this following example.

One class, core_table\external\dynamic\get, relates to a single web service, and only contains the functions which relate to that single web service.

The Web Service is defined here and named core_table_get_dynamic_table_content. It calls the function execute on the get class.

We can the define functions, like:

1. execute
2. execute_parameters
3. execute_returns
4. execute_is_deprecated
5. etc.

Rationale

1. Easier to read and work with
2. Easier migration path for if/when we decide to update our WS. We can more easily make changes web service by web service rather than wholesale
3. Easier testing
4. Ability to more easily set new language features (such as declare(strict_types=1);)
5. Fits well with our Testing Namespace issue to match individual test cases to individual web services
6. Allows for a future move away from naming services in the services.php file by requiring fixed naming, and allowing use of PHP interfaces
7. (Andrew's sanity)

Further rationale relating to future direction of web services

This change could allow for future improvements to the way in which web services are defined, for example rather than defining a new web service in the services.php, you could simply define a new class:

Location: mod/assign/classes/external/submission/submit.php
Namespace: mod_assign\external\submission
Class name: submit
Fully-qualified class name: mod_assign\external\submission\submit

Class signature:

<?php

declare(strict_types=1);

namespace mod_assign\external\submission;

use core_external\webservice;

use core_external\local\endpoints\{ajax as ajax_endpoint, mobile as mobile_endpoint};

use core_external\local\types\readwrite as type_rw;

use stdClass;

class submit extends webservice implements ajax_endpoint, mobile_endpoint, type_rw {

    public static function execute_parameters(): external_function_parameters {

        return new external_function_parameters(...);

    }

    public static function execute(...$args): stdClass {

      return (object) [...];

    }

  public static function execute_returns(): external_description {

    return new external_multiple_structure(...);

  }

  public static function execute_capabilities(): array {

    return [...];

  }

}

Description coming from the language string: external\submission\submit,mod_assign

Proposal

A) Require a single, namespaced, class per external function.
B) Fix the naming for the functions inside the class to execute

Voting

Proposal A

1. Require a single, name-spaced, class per external function
2. Require that the namespace must be in the format: <component>\external[\optional\sub\namespace]
3. Require that only functions for a single web service should exist in the class

Vote Accept

Accept proposal A in its entirety

Vote Reject

Do not accept the proposal

Proposal B

Note: This proposal's results will only be considered should Proposal A be accepted

1. Require that the method name all new web services is execute

Vote Accept

Accept proposal B in its entirety

Vote Reject

Do not accept the proposal