Assess curl commands on API pages

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

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

❗ COMMUNITY CONTRIBUTORS, PLEASE ONLY PICK UP ONE EXAMPLE FIX TO ALLOW OTHER NEW CONTRIBUTORS TO LEARN FROM THESE TOO ❗

In !175318 (comment 2261628187), Lee asked if many of the API pages need their curl commands cleaned up. Answer: yes. I’ve gradually cleaned up some of them related to my engineering groups, but there are nearly 200 files total…

How to contribute (no assignment needed)

This issue is open to multiple contributors, so you do not need to be assigned.

Pick one API doc file from the tables below (one marked ❓), then:

  1. Create a branch.
  2. Apply the implementation plan to that file’s curl examples.
  3. Open a merge request (MR) and link it back to this issue.
  4. Assign the MR to a reviewer (you can choose a Technical Writer / Docs reviewer or follow any reviewer guidance in the project).

Please only submit one file per contributor so more people can participate.

Implementation plan

The guidance for curl commands in the REST API pages is relatively new, and many of our API pages don’t have those updates yet. The needed changes:

  • Break parameters apart, one per line, with some wiggle room on the initial parameter (which is short)
    • If a method is declared
  • Each line of a multi-line curl command (except the last) should end in \ and be indented
  • Explicitly declare the --url parameter, instead of implying it.

Before:

curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/resource_milestone_events/120"

After:

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/resource_milestone_events/120"

The curl command is now multiple lines, indented, and declares the --url parameter. Less horizontal scrolling, and easier to read!

The list!

Status:

  • ❓ Curl commands unchecked. (Default status.)
  • ❌ Curl commands need cleanup.
  • ✅ Curl commands are correct.

Monitor stage

Filename Status
doc/api/alert_management_alerts.md ✅
doc/api/product_analytics.md ✅
doc/api/usage_data.md ✅
doc/api/error_tracking.md ✅

Deploy stage

Filename Status
doc/api/environments.md ✅
doc/api/group_clusters.md ✅
doc/api/deployments.md ✅
doc/api/protected_environments.md ✅
doc/api/feature_flag_user_lists.md ✅
doc/api/model_registry.md ✅
doc/api/deploy_keys.md ✅
doc/api/group_protected_environments.md ✅
doc/api/version.md ✅
doc/api/metadata.md ✅
doc/api/deploy_tokens.md ✅
doc/api/group_releases.md ✅
doc/api/feature_flags.md ✅
doc/api/features.md ✅
doc/api/instance_clusters.md ✅
doc/api/freeze_periods.md ❓
doc/api/cluster_agents.md ✅
doc/api/project_clusters.md ❓
doc/api/resource_groups.md ❓

Package stage

Filename Status
doc/api/container_registry.md ✅
doc/api/container_repository_protection_rules.md ✅
doc/api/dependency_proxy.md ✅
doc/api/packages.md ✅
doc/api/project_packages_protection_rules.md ✅

Verify stage

Filename Status
doc/api/group_level_variables.md ❓
doc/api/instance_level_ci_variables.md ✅
doc/api/job_artifacts.md ❓
doc/api/jobs.md ✅
doc/api/lint.md ❓
doc/api/merge_trains.md ❓
doc/api/pipeline_schedules.md ❓
doc/api/pipeline_triggers.md ❓
doc/api/pipelines.md ❓
doc/api/project_level_variables.md ❓
doc/api/runners.md ❓

Foundations stage

Filename Status
doc/api/bulk_imports.md ❓
doc/api/group_import_export.md ❓
doc/api/group_relations_export.md ❓
doc/api/group_webhooks.md ❓
doc/api/import.md ❓
doc/api/index.md ❓
doc/api/integrations.md ❓
doc/api/notification_settings.md ❓
doc/api/project_import_export.md ❓
doc/api/project_relations_export.md ❓
doc/api/project_webhooks.md ❓
doc/api/search.md ❓
doc/api/search_admin.md ✅
doc/api/system_hooks.md ❓
doc/api/todos.md ❓

Systems stage

Filename Status
doc/api/admin_sidekiq_queues.md ❓
doc/api/geo_nodes.md ✅
doc/api/geo_sites.md ❓
doc/api/project_repository_storage_moves.md ❓
doc/api/sidekiq_metrics.md ❓

Create stage, Source Code group

Filename Status
doc/api/branches.md ✅
doc/api/commits.md ✅
doc/api/discussions.md ✅
doc/api/group_protected_branches.md ✅
doc/api/group_push_rules.md ✅
doc/api/group_ssh_certificates.md ✅
doc/api/keys.md ✅
doc/api/merge_request_approval_settings.md ✅
doc/api/project_aliases.md ✅
doc/api/project_badges.md ✅
doc/api/project_pull_mirroring.md ✅
doc/api/project_push_rules.md ❓
doc/api/project_snippets.md ✅
doc/api/project_statistics.md ✅
doc/api/project_templates.md ✅
doc/api/protected_branches.md ✅
doc/api/protected_tags.md ❌
doc/api/remote_mirrors.md ✅
doc/api/repositories.md ✅
doc/api/repository_files.md ✅
doc/api/repository_submodules.md ❌
doc/api/snippet_repository_storage_moves.md ❓
doc/api/snippets.md ✅
doc/api/suggestions.md ✅
doc/api/tags.md ✅
doc/api/web_commits.md ✅

Create stage, other groups

Filename Status
doc/api/code_suggestions.md ❓
doc/api/draft_notes.md ✅
doc/api/group_repository_storage_moves.md ❓
doc/api/merge_request_approvals.md ✅
doc/api/merge_request_context_commits.md ✅
doc/api/merge_requests.md ✅

Plan stage, Project Management group

Filename Status
doc/api/boards.md ✅
doc/api/custom_attributes.md ❓
doc/api/emoji_reactions.md ❓
doc/api/group_boards.md ❓
doc/api/group_iterations.md ✅
doc/api/group_labels.md ✅
doc/api/group_markdown_uploads.md ✅
doc/api/group_milestones.md ❓
doc/api/issue_links.md ❓
doc/api/issues.md ❓
doc/api/issues_statistics.md ❓
doc/api/iterations.md ❓
doc/api/labels.md ❓
doc/api/milestones.md ❓
doc/api/notes.md ✅
doc/api/project_markdown_uploads.md ❓
doc/api/resource_iteration_events.md ❓
doc/api/resource_milestone_events.md ❓
doc/api/resource_state_events.md ❓
doc/api/resource_weight_events.md ❓

Plan stage, other

Filename Status
doc/api/epic_issues.md ✅
doc/api/epic_links.md ✅
doc/api/epics.md ❓
doc/api/group_activity_analytics.md ❓
doc/api/group_epic_boards.md ❓
doc/api/group_wikis.md ❓
doc/api/linked_epics.md ❓
doc/api/markdown.md ❓
doc/api/pages.md ❓
doc/api/pages_domains.md ✅
doc/api/wikis.md ✅

Data access stage

Filename Status
doc/api/database_migrations.md ❓
doc/api/group_badges.md ❓
doc/api/group_ldap_links.md ❓
doc/api/groups.md ❓
doc/api/invitations.md ❓
doc/api/organizations.md ❓
doc/api/project_forks.md ❓
doc/api/project_starring.md ❓
doc/api/projects.md ❓
doc/api/topics.md ❓

Security risk management stage

Filename Status
doc/api/dependency_list_export.md ❓
doc/api/project_vulnerabilities.md ❓
doc/api/status_checks.md ❓
doc/api/vulnerabilities.md ❓
doc/api/vulnerability_exports.md ❓
doc/api/vulnerability_findings.md ❓

Software supply chain security stage

Filename Status
doc/api/access_requests.md ✅
doc/api/appearance.md ❓
doc/api/applications.md ❓
doc/api/audit_events.md ✅
doc/api/avatar.md ✅
doc/api/events.md ❓
doc/api/google_cloud_integration.md ❓
doc/api/group_access_tokens.md ✅
doc/api/group_enterprise_users.md ❓
doc/api/group_service_accounts.md ❓
doc/api/member_roles.md ❓
doc/api/members.md ❓
doc/api/namespaces.md ✅
doc/api/oauth2.md ❓
doc/api/personal_access_tokens.md ❓
doc/api/plan_limits.md ❓
doc/api/project_access_tokens.md ✅
doc/api/project_job_token_scopes.md ❓
doc/api/resource_label_events.md ❓
doc/api/saml.md ❓
doc/api/scim.md ✅
doc/api/secure_files.md ✅
doc/api/settings.md ❓
doc/api/statistics.md ❓
doc/api/user_email_addresses.md ❓
doc/api/user_follow_unfollow.md ❓
doc/api/user_keys.md ❓
doc/api/user_moderation.md ❓
doc/api/user_service_accounts.md ❓
doc/api/user_tokens.md ❓
doc/api/users.md ❓

Other

Filename Status
doc/api/broadcast_messages.md ✅
doc/api/chat.md ❓
doc/api/dependencies.md ❓
doc/api/experiments.md ❓
doc/api/group_security_settings.md ❓
doc/api/license.md ✅
doc/api/project_container_registry_protection_rules.md ❓
doc/api/project_security_settings.md ❓
Edited by Brendan Lynch