Refactor of API landing page

- Breaks up into more sections.
- Also minor fixes to pages within sections.

1 files changed, 122 insertions, 83 deletions

diff --git a/doc/api/README.md b/doc/api/README.md
index 3b43d195390..89069fe60e1 100644
--- a/doc/api/README.md
+++ b/doc/api/README.md
@@ -1,94 +1,133 @@
 # GitLab API
 
-Automate GitLab via a simple and powerful API. All definitions can be found
-under [`/lib/api`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/api).
+Automate GitLab via a simple and powerful API.
 
 The main GitLab API is a [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) API. Therefore, documentation in this section assumes knowledge of REST concepts.
 
-## API Resources
-
-The following API resources are available:
-
-- [Applications](applications.md)
-- [Avatar](avatar.md)
-- [Award emoji](award_emoji.md)
-- [Branches](branches.md)
-- [Broadcast messages](broadcast_messages.md)
-- [Code snippets](snippets.md)
-- [Commits](commits.md)
-- [Container Registry](container_registry.md)
-- [Custom attributes](custom_attributes.md)
-- [Deploy keys](deploy_keys.md), and [deploy keys for multiple projects](deploy_key_multiple_projects.md)
-- [Deployments](deployments.md)
-- [Discussions](discussions.md) (threaded comments)
-- [Environments](environments.md)
-- [Events](events.md)
-- [Feature flags](features.md)
-- Group-related resources, including:
-  - [Groups](groups.md)
-  - [Group access requests](access_requests.md)
-  - [Group badges](group_badges.md)
-  - [Group issue boards](group_boards.md)
-  - [Group labels](group_labels.md)
-  - [Group-level variables](group_level_variables.md)
-  - [Group members](members.md)
-  - [Group milestones](group_milestones.md)
-- [Issues](issues.md)
-- [Issue boards](boards.md)
-- [Jobs](jobs.md)
-- [Keys](keys.md)
-- [Labels](labels.md)
-- [Markdown](markdown.md)
-- [Merge requests](merge_requests.md)
-- [Namespaces](namespaces.md)
-- [Notes](notes.md) (comments)
-- [Notification settings](notification_settings.md)
-- [Pages domains](pages_domains.md)
-- [Pipelines](pipelines.md)
-- [Pipeline schedules](pipeline_schedules.md)
-- [Pipeline triggers](pipeline_triggers.md) and [triggering pipelines](../ci/triggers/README.md)
-- Project-related resources, including:
-  - [Projects](projects.md) including setting Webhooks
-  - [Project access requests](access_requests.md)
-  - [Project badges](project_badges.md)
-  - [Project clusters](project_clusters.md)
-  - [Project-level variables](project_level_variables.md)
-  - [Project import/export](project_import_export.md)
-  - [Project import from GitHub](import.md)
-  - [Project members](members.md)
-  - [Project milestones](milestones.md)
-  - [Project snippets](project_snippets.md)
-  - [Project templates](project_templates.md) (see also [Templates API Resources](#templates-api-resources))
-- [Protected branches](protected_branches.md)
-- [Protected tags](protected_tags.md)
-- [Repositories](repositories.md)
-- [Repository files](repository_files.md)
-- [Repository submodules](repository_submodules.md)
-- [Resource label events](resource_label_events.md)
-- [Runners](runners.md)
-- [Search](search.md)
-- [Services](services.md)
-- [Settings](settings.md)
-- [Sidekiq metrics](sidekiq_metrics.md)
-- [System hooks](system_hooks.md)
-- [Tags](tags.md)
-- [Releases](releases/index.md)
-- Release Assets
-  - [Links](releases/links.md)
-- [Todos](todos.md)
-- [Users](users.md)
-- [Validate CI configuration](lint.md) (linting)
-- [Version](version.md)
-- [Wikis](wikis.md)
-
-See also [V3 to V4](v3_to_v4.md).
-
-### Templates API Resources
+## API resources
+
+Available API resources can be grouped in the following contexts:
+
+- [Projects](#project-resources).
+- [Groups](#group-resources).
+- [Standalone](#standalone-resources).
+
+See also:
+
+- [V3 to V4](v3_to_v4.md).
+- Adding [deploy keys for multiple projects](deploy_key_multiple_projects.md).
+
+### Project resources
+
+The following API resources are available in the project context:
+
+| Resource                                              | Available endpoints                                                                                                                                                       |
+|:------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [Access requests](access_requests.md)                 | `/projects/:id/access_requests` (also available for groups)                                                                                                               |
+| [Award emoji](award_emoji.md)                         | `/projects/:id/issues/.../award_emoji`, `/projects/:id/merge_requests/.../award_emoji`, `/projects/:id/snippets/.../award_emoji`                                          |
+| [Branches](branches.md)                               | `/projects/:id/repository/branches/`, `/projects/:id/repository/merged_branches`                                                                                          |
+| [Commits](commits.md)                                 | `/projects/:id/repository/commits`, `/projects/:id/statuses`                                                                                                              |
+| [Container Registry](container_registry.md)           | `/projects/:id/registry/repositories`                                                                                                                                     |
+| [Custom attributes](custom_attributes.md)             | `/projects/:id/custom_attributes` (also available for groups and users)                                                                                                   |
+| [Deploy keys](deploy_keys.md)                         | `/projects/:id/deploy_keys` (also available standalone)                                                                                                                   |
+| [Deployments](deployments.md)                         | `/projects/:id/deployments`                                                                                                                                               |
+| [Discussions](discussions.md) (threaded comments)     | `/projects/:id/issues/.../discussions`, `/projects/:id/snippets/.../discussions`, `/projects/:id/merge_requests/.../discussions`, `/projects/:id/commits/.../discussions` |
+| [Environments](environments.md)                       | `/projects/:id/environments`                                                                                                                                              |
+| [Events](events.md)                                   | `/projects/:id/events` (also available for users and standalone)                                                                                                          |
+| [Issues](issues.md)                                   | `/projects/:id/issues` (also available for groups and standalone)                                                                                                         |
+| [Issue boards](boards.md)                             | `/projects/:id/boards`                                                                                                                                                    |
+| [Jobs](jobs.md)                                       | `/projects/:id/jobs`, `/projects/:id/pipelines/.../jobs`                                                                                                                  |
+| [Labels](labels.md)                                   | `/projects/:id/labels`                                                                                                                                                    |
+| [Members](members.md)                                 | `/projects/:id/members` (also available for groups)                                                                                                                       |
+| [Merge requests](merge_requests.md)                   | `/projects/:id/merge_requests` (also available for groups and standalone)                                                                                                 |
+| [Notes](notes.md) (comments)                          | `/projects/:id/issues/.../notes`, `/projects/:id/snippets/.../notes`, `/projects/:id/merge_requests/.../notes`                                                            |
+| [Notification settings](notification_settings.md)     | `/projects/:id/notification_settings` (also available for groups and standalone)                                                                                          |
+| [Pages domains](pages_domains.md)                     | `/projects/:id/pages` (also available standalone)                                                                                                                         |
+| [Pipelines](pipelines.md)                             | `/projects/:id/pipelines`                                                                                                                                                 |
+| [Pipeline schedules](pipeline_schedules.md)           | `/projects/:id/pipeline_schedules`                                                                                                                                        |
+| [Pipeline triggers](pipeline_triggers.md)             | `/projects/:id/triggers`                                                                                                                                                  |
+| [Projects](projects.md) including setting Webhooks    | `/projects`, `/projects/:id/hooks` (also available for users)                                                                                                             |
+| [Project badges](project_badges.md)                   | `/projects/:id/badges`                                                                                                                                                    |
+| [Project clusters](project_clusters.md)               | `/projects/:id/clusters`                                                                                                                                                  |
+| [Project-level variables](project_level_variables.md) | `/projects/:id/variables`                                                                                                                                                 |
+| [Project import/export](project_import_export.md)     | `/projects/:id/export`, `/projects/import`, `/projects/:id/import`                                                                                                        |
+| [Project milestones](milestones.md)                   | `/projects/:id/milestones`                                                                                                                                                |
+| [Project snippets](project_snippets.md)               | `/projects/:id/snippets`                                                                                                                                                  |
+| [Project templates](project_templates.md)             | `/projects/:id/templates`                                                                                                                                                 |
+| [Protected branches](protected_branches.md)           | `/projects/:id/protected_branches`                                                                                                                                        |
+| [Protected tags](protected_tags.md)                   | `/projects/:id/protected_tags`                                                                                                                                            |
+| [Releases](releases/index.md)                         | `/projects/:id/releases`                                                                                                                                                  |
+| [Release links](releases/links.md)                    | `/projects/:id/releases/.../assets/links`                                                                                                                                 |
+| [Repositories](repositories.md)                       | `/projects/:id/repository`                                                                                                                                                |
+| [Repository files](repository_files.md)               | `/projects/:id/repository/files`                                                                                                                                          |
+| [Repository submodules](repository_submodules.md)     | `/projects/:id/repository/submodules`                                                                                                                                     |
+| [Resource label events](resource_label_events.md)     | `/projects/:id/issues/.../resource_label_events`, `/projects/:id/merge_requests/.../resource_label_events`                                                                |
+| [Runners](runners.md)                                 | `/projects/:id/runners` (also available standalone)                                                                                                                       |
+| [Search](search.md)                                   | `/projects/:id/search` (also available for groups and standalone)                                                                                                         |
+| [Services](services.md)                               | `/projects/:id/services`                                                                                                                                                  |
+| [Tags](tags.md)                                       | `/projects/:id/repository/tags`                                                                                                                                           |
+| [Wikis](wikis.md)                                     | `/projects/:id/wikis`                                                                                                                                                     |
+
+### Group resources
+
+The following API resources are available in the group context:
+
+| Resource                                          | Available endpoints                                                              |
+|:--------------------------------------------------|:---------------------------------------------------------------------------------|
+| [Access requests](access_requests.md)             | `/groups/:id/access_requests/` (also available for projects)                     |
+| [Custom attributes](custom_attributes.md)         | `/groups/:id/custom_attributes` (also available for projects and users)          |
+| [Groups](groups.md)                               | `/groups`, `/groups/.../subgroups`                                               |
+| [Group badges](group_badges.md)                   | `/groups/:id/badges`                                                             |
+| [Group issue boards](group_boards.md)             | `/groups/:id/boards`                                                             |
+| [Group labels](group_labels.md)                   | `/groups/:id/labels`                                                             |
+| [Group-level variables](group_level_variables.md) | `/groups/:id/variables`                                                          |
+| [Group milestones](group_milestones.md)           | `/groups/:id/milestones`                                                         |
+| [Issues](issues.md)                               | `/groups/:id/issues` (also available for projects and standalone)                |
+| [Members](members.md)                             | `/groups/:id/members` (also available for projects)                              |
+| [Merge requests](merge_requests.md)               | `/groups/:id/merge_requests` (also available for projects and standalone)        |
+| [Notification settings](notification_settings.md) | `/groups/:id/notification_settings` (also available for projects and standalone) |
+| [Search](search.md)                               | `/groups/:id/search` (also available for projects and standalone)                |
+
+### Standalone resources
+
+The following API resources are available outside of project and group contexts (including `/users`):
+
+| Resource                                          | Available endpoints                                                     |
+|:--------------------------------------------------|:------------------------------------------------------------------------|
+| [Applications](applications.md)                   | `/applications`                                                         |
+| [Avatar](avatar.md)                               | `/avatar`                                                               |
+| [Broadcast messages](broadcast_messages.md)       | `/broadcast_messages`                                                   |
+| [Code snippets](snippets.md)                      | `/snippets`                                                             |
+| [Custom attributes](custom_attributes.md)         | `/users/:id/custom_attributes` (also available for groups and projects) |
+| [Deploy keys](deploy_keys.md)                     | `/deploy_keys` (also available for projects)                            |
+| [Events](events.md)                               | `/events`, `/users/:id/events` (also available for projects)            |
+| [Feature flags](features.md)                      | `/features`                                                             |
+| [Import repository from GitHub](import.md)        | `/import/github`                                                        |
+| [Issues](issues.md)                               | `/issues` (also available for groups and projects)                      |
+| [Keys](keys.md)                                   | `/keys`                                                                 |
+| [Markdown](markdown.md)                           | `/markdown`                                                             |
+| [Merge requests](merge_requests.md)               | `/merge_requests` (also available for groups and projects)              |
+| [Namespaces](namespaces.md)                       | `/namespaces`                                                           |
+| [Notification settings](notification_settings.md) | `/notification_settings` (also available for groups and projects)       |
+| [Pages domains](pages_domains.md)                 | `/pages/domains` (also available for projects)                          |
+| [Projects](projects.md)                           | `/users/:id/projects` (also available for projects)                     |
+| [Runners](runners.md)                             | `/runners` (also available for projects)                                |
+| [Search](search.md)                               | `/search` (also available for groups and projects)                      |
+| [Settings](settings.md)                           | `/application/settings`                                                 |
+| [Sidekiq metrics](sidekiq_metrics.md)             | `/sidekiq`                                                              |
+| [Suggestions](suggestions.md)                     | `/suggestions`                                                          |
+| [System hooks](system_hooks.md)                   | `/hooks`                                                                |
+| [Todos](todos.md)                                 | `/todos`                                                                |
+| [Users](users.md)                                 | `/users`                                                                |
+| [Validate `.gitlab-ci.yml` file](lint.md)         | `/lint`                                                                 |
+| [Version](version.md)                             | `/version`                                                              |
+
+### Templates API resources
 
 Endpoints are available for:
 
 - [Dockerfile templates](templates/dockerfiles.md).
-- [gitignore templates](templates/gitignores.md).
+- [`.gitignore` templates](templates/gitignores.md).
 - [GitLab CI YAML templates](templates/gitlab_ci_ymls.md).
 - [Open source license templates](templates/licenses.md).
 
@@ -110,7 +149,7 @@ have been resolved to our satisfaction by the relicensing of the reference
 implementations under MIT, and the use of the OWF license for the GraphQL
 specification.
 
-## Compatibility Guidelines
+## Compatibility guidelines
 
 The HTTP API is versioned using a single number, the current one being 4. This
 number symbolizes the same as the major version number as described by