Repository navigation
Update REST Style Guide - #1732
Open
andrewnicols wants to merge 10 commits into
Open
andrewnicols wants to merge 10 commits into
andrewnicols wants to merge 10 commits into
Conversation
Allow documented processing controls and permission-limited creation representations. Distinguish administrative credential workflows from privacy-preserving public recovery requests. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Generalise public access guidance to templates, language strings and recovery. Require the unscoped_resource PHP attribute and distinguish scope exemptions from authentication and capability checks. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
AE-215 user representations return null for hidden email/profile fields and unavailable last-access timestamps. Declare these nullable in OpenAPI without exposing why a value is unavailable or confusing a readable empty string with null. Keep request nullability independent: a nullable user response must not imply that PATCH accepts null to clear that field. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
In AE-215 an invalid email, unknown PATCH field or incompatible password-generation option is well-formed input that fails validation, not malformed JSON. Require 422 for these cases and reserve 400 for requests that cannot be interpreted, consistently across router and handler validation. Keep duplicate usernames at 409, authentication-plugin field locks at 403, and stale ETags at 412 so clients can distinguish corrective actions. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
AE-215 user and custom-field updates need actionable errors for fields such as profile.country and customFields.fields.studentcode. Define details entries containing field, code and message rather than the guide's conflicting nested error envelope. Stable lowercase codes support integrations while translated messages support forms. Collect independent failures where practical without promising exhaustive validation, and never echo passwords or reset tokens. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
AE-215 exposes one profile and one managed password beneath each user. Requiring /profiles or /passwords would imply collections that do not exist, so allow singular nouns for genuine singleton subresources. Retain plural nouns for users, custom-fields and password-resets collections, together with the existing noun-only and kebab-case conventions. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…ibility AE-215 creation clients need to recognise usernameexists rather than parse translated conflict messages. Require a top-level code for documented application-specific problems while allowing generic HTTP/framework failures to use status and RFC 9457 type alone. Preserve the meaning of deprecated numeric errorcode members until normal removal. Do not overload problem-type URIs or expose account-existence outcomes through public recovery codes. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
AE-215 already exposes user profile and custom-field resources independently. Mandatory expansion on every single-resource GET would add a response shape and authorisation contract without an established use case. Allow expansion where useful, requiring documented syntax, relationships, shape, permission filtering and cost/depth limits. Do not choose a global expansion envelope or require new expansion work on the user endpoints. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The AE-215 reset flows need submission and an immediate outcome, not a history of separately addressable reset records. Use singular password-reset paths consistently with singleton naming, removing the invented result GET, identifiers and retention requirement. Distinguish processing POST responses from creation: return 200 for a synchronous outcome, 204 without a body or 202 for accepted processing. Preserve 201 and Location for workflows that really create addressable resources. Public recovery retains its generic 202 and privacy protections. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
✅ Deploy Preview for moodledevdocs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
There was a problem hiding this comment.
🟢 Approval recommended
No blocking issues were identified across the three changed files, and neither documentation page requires versioned backports.
No open issues 🎉
What changed in this PR
This PR refines Moodle’s REST API style guide to support practical endpoint requirements while retaining consistent resource naming, error handling, and access controls.
Changes:
- Clarifies singleton resources, optional expansion, nullable responses, and RFC 9457-compatible errors.
- Defines mutation processing controls, workflow resources, public account recovery, and explicit unscoped declarations.
- Updates development browser targets and corrects the React theming warning’s admonition type.
| File | Description |
|---|---|
package.json |
Broadens development browser targets to match production. |
docs/guides/rest/style.md |
Refines REST endpoint contracts and security requirements. |
docs/guides/javascript/react/theming.md |
Changes the circular-dependency warning to a danger admonition. |
Review effort: Balanced
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
In the creation of the first set of endpoints I encountered a few issues with the REST Style Guide:
move: 'up') should be banned, some processing control mutations should be allowed - these are things which are instructions for the server to modify the record in a way that cannot be otherwise calculated, for example:generatePasswordsendPasswordEmail