Docs: Standardize API operation names and descriptions

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

Hi community contributors! 👋

Do you want to work on this issue? Please follow all instructions below, and please work on only 3 files at a time, to give everyone a chance to contribute. Thank you!

MRs created for this issue between January 22 and January 29, 2026, are eligible for the latest GitLab Hackathon!

If you are new contributing, see: https://about.gitlab.com/community/contribute/. The linked tutorial will help you get started as a contributor!

Problem to solve

The markdown API documentation files in /doc/api/ use inconsistent operation names and descriptions. We need to standardize these to follow GitLab's RESTful API style guide for better consistency and clarity across all API documentation.

Implementation plan

You don't need to be assigned to this issue to work on it. To contribute:

  1. Review the list of available files in /doc/api/ and put your username next to the files you want to work on. Please choose only 3 files at a time, to give everyone a chance. When you have completed work on those files, you can start working on the next batch of files.
  2. Review operation titles and descriptions for the files.
  3. Standardize the titles to use approved verbs.
    • The title is the section heading for operation. For example: ## Create an application, ## List all events, or ### Create a group access token.
    • Many operations may already use the standard verb (or the verb that best matches the operation).
    • For details, see Operation titles.
  4. Standardize the first sentence of the operation description.
    • The description is the paragraph after the heading, or history or details blocks.
    • This first sentence should broadly match what is used for the heading. For example: Creates an application, List all events associated with the user, or Creates a group access token for a specified group.
    • For details, see Operation description.
  5. Open a merge request using the Documentation merge request description template. Include all your changes in a single MR, do not open multiple MRs for changes to the same file.
  6. In the merge request description, include this text: https://gitlab.com/gitlab-org/gitlab/-/work_items/585399

After your MR is merged, update the spreadsheet and select 'Merged'.

Examples

Updated headings

Update the titles for each operation to use consistent verbs based on HTTP method. For details on the recommended verbs for each HTTP method, see Operation titles.

HTTP Method Original Updated
GET (Singleton) List projects and groups that a user is a member of Retrieve membership list for a user
GET (Singleton) Get a single pipeline Retrieve a pipeline
GET (List) List project pipelines List all project pipelines
GET (List) List group issues List all group issues
PUT Update pipeline metadata Update a pipeline
POST Create repository branch Create a repository branch
POST Protect repository branch Protect a repository branch
DELETE Unprotect repository branch Unprotect a repository branch
DELETE Delete a pipeline Delete a pipeline

Note

The style guide verb list is not comprehensive. There may be times when a non-standard verb just makes more sense. Use your best judgment!

Updated introduction

Update the first sentence for the description of each operation based on the title. For details, see Operation description. The first sentence should broadly repeat the title of the operation.

In many cases it can be helpful to add a little more context to this sentence. Generally, it can be helpful to highlight the most important element from the path param. For example, if the request includes a specific group ID, you may want to mention that in the description (Remove a member from a specified group).Sometimes there may be multiple elements in the request path, just use your best judgement to highlight the most important element. For example, Deletes a specified issue from a specified project sounds redundant, but Deletes a specified issue from a project still gets the point across.

If you don't feel confident in adding this extra context, it's still totally acceptable to just use the basic structure.

HTTP Method Original Basic Advanced
GET (Singleton) List projects and groups that a user is a member of Retrieve membership list for a user Retrieves the membership list for a specified user
GET (Singleton) Retrieve a pipeline Retrieves a pipeline Retrieves a specified pipeline for a project
GET (List) List all project pipelines Lists all project pipelines Lists all pipelines for a specified project
GET (List) List all group issues Lists all group issues Lists all issues for a specified group
PUT Update a pipeline Updates a pipeline Updates a specified pipeline for a project
POST Create a repository branch Creates a repository branch Creates a repository branch for a specified project
POST Protect a repository branch Protects a repository branch Protects a specified repository branch for a project
DELETE Unprotect a repository branch Unprotects a repository branch Unprotects a specified repository branch for a project
DELETE Delete a pipeline Deletes a pipeline Deletes a specified pipeline for a project

Note

  • It may be common for you to only need to update the description and the title may be correct.
  • There may be existing content already used in the description. If so, just add the standard structure first, and adjust the existing text to fit.

Who can address the issue

Community contributors with familiarity with GitLab's API documentation and the RESTful API style guide. No special expertise required—this is a great opportunity for documentation improvements.

Other links/references

Available files

(To be updated by GitLab team members)

Completed

Click to expand

In progress

Click to expand

Need to complete

Click to expand
Edited by Isaac Durham