<!--IssueSummary start--> <details> <summary> Everyone can contribute. [Help move this issue forward](https://handbook.gitlab.com/handbook/marketing/developer-relations/contributor-success/community-contributors-workflows/#contributor-links) while earning points, leveling up and collecting rewards. </summary> - [Collaborate/take over this issue](https://contributors.gitlab.com/manage-issue?action=work&projectId=278964&issueIid=433318) </details> <!--IssueSummary end--> ## Problem to solve The merge request API page (https://docs.gitlab.com/ee/api/merge_requests.html) is old, and is missing some expected content for its various endpoints. The docs for each endpoint should contain all of the pieces of content described in the [REST API topic template](https://docs.gitlab.com/ee/development/documentation/restful_api_styleguide.html#api-topic-template). These are the components each subheading is supposed to have, and I'll bold the ones that are commonly missing or problematic: 1. 1-2 sentence description of the endpoint 1. A code block with the method. 1. A table of the attributes this endpoint accepts / requires 1. **The success status code this endpoint returns** 1. **(optional) The failure status codes this endpoint returns**, if atypical, see https://gitlab.com/gitlab-org/gitlab/-/issues/433318#note_1828215969 1. **A table of the response attributes** 1. **An example `curl` request** 1. An example response in `JSON` format I've created a thread in this issue for each of the subheadings. (This work is part of my current quarter OKR, https://gitlab.com/gitlab-org/technical-writing/-/issues/936.) ## Proposal 1. [x] Amy to review the API page, identify what's missing from each endpoint 1. [x] Amy to post a checklist here to show what's needed 1. ~~Amy to work with @kisha.mavryck and @phikai to ensure this work is handed to the engineers~~ 1. [ ] François / Amy work together to fix the gaps in the page. ## Who can address the issue The ~"group::code review" team, in conjunction with their TW. (Me!) ## Other links/references Related to https://gitlab.com/gitlab-org/technical-writing/-/issues/936+ ## Status - API endpoints to document Legend: - [x] Done - [ ] TODO - [~] - Out of scope List of MR-related endpoints by order of average requests per seconds (looking at past 7 days). The higher the RPS, the more traffic the endpoints gets, and therefore the more valuable it is to document it. Assumption is that more traffic => more user interest. See https://gitlab.com/gitlab-org/gitlab/-/issues/433318#note_1785454140. [Grafana dashboard (past 7 days)](https://dashboards.gitlab.net/d/stage-groups-code_review/stage-groups3a-code-review3a-group-dashboard?orgId=1&viewPanel=18&from=now-7d&to=now) ### HIGH usage (5) - 40% done - **> 100 RPS** (1) - 100% done :white_check_mark: - [~] `~execute` - [x] `GET /api/projects/:id/merge_requests` - https://gitlab.com/gitlab-org/gitlab/-/issues/433318#note_1693466977 - **10-100 RPS** (4) - 50% done - [~] `GET /api/projects/:id/merge_requests/:noteable_id/notes` - [x] `GET /api/projects/:id/merge_requests/:merge_request_iid` - https://gitlab.com/gitlab-org/gitlab/-/issues/433318#note_1693467314 - [x] `GET /api/projects/:id/merge_requests/:merge_request_iid/commits` - https://gitlab.com/gitlab-org/gitlab/-/issues/433318#note_1693467748 - [x] `GET /api/groups/id/merge_requests` - https://gitlab.com/gitlab-org/gitlab/-/issues/433318#note_1693467141 - [~] `GET /api/projects/:id/merge_requests/:noteable_id/discussions` - [~] `GET /api/projects/:id/merge_requests/:merge_request_iid/award_emoji` - [x] `GET /api/projects/:id/merge_requests/:merge_request_iid/closes_issues` - https://gitlab.com/gitlab-org/gitlab/-/issues/433318#note_1693478467 ### MEDIUM usage (7) - 14% done - **1-10 RPS** (4) - 25% done - [~] `GET /api/merge_requests` - [ ] `PUT /api/projects/:id/merge_requests/:merge_request_iid/merge` - https://gitlab.com/gitlab-org/gitlab/-/issues/433318#note_1693468662 - [ ] `PUT /api/projects/:id/merge_requests/:merge_request_iid` - https://gitlab.com/gitlab-org/gitlab/-/issues/433318#note_1693468365 - [~] `GET /api/projects/:id/merge_requests/:noteable_id/notes/:note_id` - [x] `GET /api/projects/:id/merge_requests/:merge_request_iid/versions/:version_id` - https://gitlab.com/gitlab-org/gitlab/-/issues/433318#note_1693479402 - [~] `GET /api/projects/:id/merge_requests/:merge_request_iid/changes` - [~] `GET /api/projects/:id/merge_requests/:merge_request_iid/notes/:note_id/award_emoji` - [~] `PUT /api/projects/:id/merge_requests/:noteable_id/notes/:note_id` - [ ] `GET /api/projects/:id/merge_requests/:merge_request_iid/versions` - https://gitlab.com/gitlab-org/gitlab/-/issues/433318#note_1693479285 - [~] `POST /api/projects/:id/merge_requests/:noteable_id/notes` - **0.1-1 RPS** (3) - 0% done - [ ] `GET /api/projects/:id/merge_requests/:merge_request_iid/reviewers` - https://gitlab.com/gitlab-org/gitlab/-/issues/433318#note_1693467597 - [~] `GET /api/projects/:id/merge_requests/:merge_request_iid/diffs` - [ ] `POST /api/projects/:id/merge_requests` - https://gitlab.com/gitlab-org/gitlab/-/issues/433318#note_1693468250 - [~] `GET /api/projects/:id/merge_requests/:eventable_id/resource_label_events` - [~] `GET /api/projects/:id/merge_requests/:eventable_id/resource_state_events` - [~] `DELETE /api/projects/:id/merge_requests/:noteable_id/notes/:note_id` - [ ] `GET /api/projects/:id/merge_requests/:merge_request_iid/participants` - https://gitlab.com/gitlab-org/gitlab/-/issues/433318#note_1693467404 - [~] `GET /api/projects/:id/merge_requests/:merge_request_iid/draft_notes` ### LOW usage (8) - 0% done - **0.01-0.1 RPS** (2) - 0% done - [~] `PUT /api/projects/:id/merge_requests/:noteable_id/discussions/:discussion_id/notes/:note_id` - [~] `POST /api/projects/:id/merge_requests/:noteable_id/discussions` - [~] `PUT /api/projects/:id/merge_requests/:noteable_id/discussions/:discussion_id` - [~] `POST /api/projects/:id/merge_requests/:merge_request_iid/award_emoji` - [~] `GET /api/projects/:id/merge_requests/:merge_request_iid/related_issues` - [ ] `PUT /api/projects/:id/merge_requests/:merge_request_iid/rebase` - https://gitlab.com/gitlab-org/gitlab/-/issues/433318#note_1693478283 - [~] `GET /api/projects/:id/merge_requests/:noteable_id/discussions/:discussion_id/notes/:note_id` - [ ] `DELETE /api/projects/:id/merge_requests/:merge_request_iid` - https://gitlab.com/gitlab-org/gitlab/-/issues/433318#note_1693468525 - [~] `GET /api/projects/:id/merge_requests/:eventable_id/resource_milestone_events` - **<0.01 RPS** (6) - 0% done - [ ] `POST /api/projects/:id/merge_requests/:merge_request_iid/cancel_merge_when_pipeline_succeeds` - https://gitlab.com/gitlab-org/gitlab/-/issues/433318#note_1693469357 - [ ] `GET /api/projects/:id/merge_requests/:merge_request_iid/merge_ref` - https://gitlab.com/gitlab-org/gitlab/-/issues/433318#note_1693468855 - [ ] `POST /api/projects/:id/merge_requests/:subscribable_id/subscribe` - https://gitlab.com/gitlab-org/gitlab/-/issues/433318#note_1693478671 - [ ] `POST /api/projects/:id/merge_requests/:subscribable_id/unsubscribe` - https://gitlab.com/gitlab-org/gitlab/-/issues/433318#note_1693478946 - [ ] `POST /api/projects/:id/merge_requests/:merge_request_iid/time_estimate` - https://gitlab.com/gitlab-org/gitlab/-/issues/433318#note_1693479519 - [ ] `GET /projects/:id/merge_requests/:merge_request_iid/time_stats` - https://gitlab.com/gitlab-org/gitlab/-/issues/433318#note_1693480039 21 more endpoints, not listed here.