[go: up one dir, main page]
Skip to content

Fix missing data / structure in Merge Request API page

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

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. 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
  2. A code block with the method.
  3. A table of the attributes this endpoint accepts / requires
  4. The success status code this endpoint returns
  5. (optional) The failure status codes this endpoint returns, if atypical, see #433318 (comment 1828215969)
  6. A table of the response attributes
  7. An example curl request
  8. 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. Amy to review the API page, identify what's missing from each endpoint
  2. Amy to post a checklist here to show what's needed
  3. Amy to work with @kisha.mavryck and @phikai to ensure this work is handed to the engineers
  4. François / Amy work together to fix the gaps in the page.

Who can address the issue

The groupcode 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:

  • 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 #433318 (comment 1785454140).

Grafana dashboard (past 7 days)

HIGH usage (5) - 40% done

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 - #433318 (comment 1693468662)
    • PUT /api/projects/:id/merge_requests/:merge_request_iid - #433318 (comment 1693468365)
    • GET /api/projects/:id/merge_requests/:noteable_id/notes/:note_id
    • GET /api/projects/:id/merge_requests/:merge_request_iid/versions/:version_id - #433318 (comment 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 - #433318 (comment 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 - #433318 (comment 1693467597)
    • GET /api/projects/:id/merge_requests/:merge_request_iid/diffs
    • POST /api/projects/:id/merge_requests - #433318 (comment 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 - #433318 (comment 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 - #433318 (comment 1693478283)
    • GET /api/projects/:id/merge_requests/:noteable_id/discussions/:discussion_id/notes/:note_id
    • DELETE /api/projects/:id/merge_requests/:merge_request_iid - #433318 (comment 1693468525)
    • GET /api/projects/:id/merge_requests/:eventable_id/resource_milestone_events

  • <0.01 RPS (6) - 0% done

21 more endpoints, not listed here.

Edited by Amy Qualls