[docs] Initial draft of the REST style guide#1649
Draft
andrewnicols wants to merge 1 commit into
Draft
Conversation
✅ 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.
Pull request overview
Adds a new REST documentation section to the Moodle DevDocs site, including an initial (but intended-to-be-normative) REST API style guide to standardize URI structure, naming, payload conventions, and HTTP semantics across Moodle components.
Changes:
- Introduces a comprehensive REST API style guide covering resource design, URI conventions, JSON conventions, pagination, errors, and idempotency.
- Adds a
RESTguide index page underdocs/guides/rest/.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 10 comments.
| File | Description |
|---|---|
| docs/guides/rest/style.md | Adds the initial REST style guide content and examples. |
| docs/guides/rest/index.md | Adds the REST guides section index frontmatter (and should include navigational content). |
Comments suppressed due to low confidence (2)
docs/guides/rest/style.md:998
- This TODO note also uses broken Markdown emphasis ("-*TO DO:**"). Formatting it consistently will improve readability of the draft.
-*TO DO:** this section is under revision; most of it is being removed as incorrect, so its rationale will be drafted once the replacement content is agreed.
docs/guides/rest/index.md:7
docs/guides/rest/index.mdcurrently contains only frontmatter, so the rendered page will be empty. Adding a short introduction and links (e.g. to the style guide) will make the section navigable.
---
Comment on lines
+83
to
+86
| GET /courses/{courseid} | ||
| POST /courses | ||
| PATCH /courses/{courseid} | ||
| DELETE /courses/{courseid} |
|
|
||
| ### 7.1 Nested Resources | ||
|
|
||
| Nested resources MUST only be used only for direct ownership or containment relationships. |
Comment on lines
+436
to
+441
| { | ||
| "courseId": 42, | ||
| "shortName": "math101", | ||
| "createdAt": 1779193800, | ||
| "startDate": 1779193800 | ||
| } |
Comment on lines
+524
to
+529
| "pagination": { | ||
| "page": 1, | ||
| "pagesize": 25, | ||
| "totalitems": 1 | ||
| } | ||
| } |
Comment on lines
+617
to
+622
| "pagination": { | ||
| "page": 1, | ||
| "pagesize": 25, | ||
| "totalitems": 100 | ||
| } | ||
| } |
|
|
||
| #### RATIONALE | ||
|
|
||
| -*TO DO:** this rationale needs further work — the scope naming examples in this section are still under review and will be revised before this rationale is finalized. |
Comment on lines
+900
to
+902
| - OAuth2 | ||
| - ****** Service tokens | ||
|
|
|
|
||
| #### RATIONALE | ||
|
|
||
| Declarative payloads describe what the resource should look like afterwards, which is idempotent, easy to validate against a schema, and safe to retry. Imperative payloads like "move": "up" encode a transition rather than a state, so retries or race conditions between two clients could produce different results depending on execution order, undermining PATCH's idempotency expectations from section 15.2. |
Comment on lines
+331
to
+332
| /courses/{courseid}/sections | ||
| /mod_forum/It was /{discussionid}/posts/{postid} |
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.
This is the initial draft of the REST style guide for RFC.