From fb6e59ebe34f4c51c212ce0587a9a48066081fd7 Mon Sep 17 00:00:00 2001 From: Evan Read Date: Fri, 15 Feb 2019 09:39:23 +0000 Subject: Refactor of API landing page - Breaks up into more sections. - Also minor fixes to pages within sections. --- doc/api/README.md | 205 +++++++++++++++++++++++---------------- doc/api/lint.md | 2 +- doc/api/pages_domains.md | 12 +-- doc/api/project_import_export.md | 27 +++--- doc/api/protected_branches.md | 1 + doc/api/releases/index.md | 2 +- doc/api/templates/gitignores.md | 12 +-- 7 files changed, 150 insertions(+), 111 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 diff --git a/doc/api/lint.md b/doc/api/lint.md index a0307f7081d..71c09d35b8c 100644 --- a/doc/api/lint.md +++ b/doc/api/lint.md @@ -2,7 +2,7 @@ > [Introduced][ce-5953] in GitLab 8.12. -Checks if your .gitlab-ci.yml file is valid. +Checks if your `.gitlab-ci.yml` file is valid. ``` POST /lint diff --git a/doc/api/pages_domains.md b/doc/api/pages_domains.md index 4c41350dcdb..70fbe24099f 100644 --- a/doc/api/pages_domains.md +++ b/doc/api/pages_domains.md @@ -8,7 +8,7 @@ The GitLab Pages feature must be enabled to use these endpoints. Find out more a Get a list of all pages domains. The user must have admin permissions. -```http +```text GET /pages/domains ``` @@ -34,7 +34,7 @@ curl --header "PRIVATE-TOKEN: " https://gitlab.example.com/ap Get a list of project pages domains. The user must have permissions to view pages domains. -```http +```text GET /projects/:id/pages/domains ``` @@ -69,7 +69,7 @@ curl --header "PRIVATE-TOKEN: " https://gitlab.example.com/ap Get a single project pages domain. The user must have permissions to view pages domains. -```http +```text GET /projects/:id/pages/domains/:domain ``` @@ -110,7 +110,7 @@ curl --header "PRIVATE-TOKEN: " https://gitlab.example.com/ap Creates a new pages domain. The user must have permissions to create new pages domains. -```http +```text POST /projects/:id/pages/domains ``` @@ -146,7 +146,7 @@ curl --request POST --header "PRIVATE-TOKEN: " --form "domain Updates an existing project pages domain. The user must have permissions to change an existing pages domains. -```http +```text PUT /projects/:id/pages/domains/:domain ``` @@ -182,7 +182,7 @@ curl --request PUT --header "PRIVATE-TOKEN: " --form "certifi Deletes an existing project pages domain. -```http +```text DELETE /projects/:id/pages/domains/:domain ``` diff --git a/doc/api/project_import_export.md b/doc/api/project_import_export.md index fc91c5741da..5155e996158 100644 --- a/doc/api/project_import_export.md +++ b/doc/api/project_import_export.md @@ -1,8 +1,8 @@ # Project import/export API -[Introduced][ce-41899] in GitLab 10.6 +> [Introduced][ce-41899] in GitLab 10.6. -[See also the project import/export documentation](../user/project/settings/import_export.md) +See also the [project import/export documentation](../user/project/settings/import_export.md). ## Schedule an export @@ -16,7 +16,7 @@ data file uploads to the final server. If the `upload` params is present, `upload[url]` param is required. (**Note:** This feature was introduced in GitLab 10.7) -```http +```text POST /projects/:id/export ``` @@ -28,8 +28,7 @@ POST /projects/:id/export | `upload[url]` | string | yes | The URL to upload the project | | `upload[http_method]` | string | no | The HTTP method to upload the exported project. Only `PUT` and `POST` methods allowed. Default is `PUT` | - -```console +```sh curl --request POST --header "PRIVATE-TOKEN: " https://gitlab.example.com/api/v4/projects/1/export \ --data "upload[http_method]=PUT" \ --data-urlencode "upload[url]=https://example-bucket.s3.eu-west-3.amazonaws.com/backup?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIMBJHN2O62W8IELQ%2F20180312%2Feu-west-3%2Fs3%2Faws4_request&X-Amz-Date=20180312T110328Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=8413facb20ff33a49a147a0b4abcff4c8487cc33ee1f7e450c46e8f695569dbd" @@ -45,7 +44,7 @@ curl --request POST --header "PRIVATE-TOKEN: " https://gitlab Get the status of export. -```http +```text GET /projects/:id/export ``` @@ -53,7 +52,7 @@ GET /projects/:id/export | --------- | -------------- | -------- | ---------------------------------------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | -```console +```sh curl --header "PRIVATE-TOKEN: " https://gitlab.example.com/api/v4/projects/1/export ``` @@ -86,7 +85,7 @@ to a web server, etc. Download the finished export. -```http +```text GET /projects/:id/export/download ``` @@ -94,18 +93,18 @@ GET /projects/:id/export/download | --------- | -------------- | -------- | ---------------------------------------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | -```console +```sh curl --header "PRIVATE-TOKEN: " --remote-header-name --remote-name https://gitlab.example.com/api/v4/projects/5/export/download ``` -```console +```sh ls *export.tar.gz 2017-12-05_22-11-148_namespace_project_export.tar.gz ``` ## Import a file -```http +```text POST /projects/import ``` @@ -124,7 +123,7 @@ cURL to post data using the header `Content-Type: multipart/form-data`. The `file=` parameter must point to a file on your file system and be preceded by `@`. For example: -```console +```sh curl --request POST --header "PRIVATE-TOKEN: " --form "path=api-project" --form "file=@/path/to/file" https://gitlab.example.com/api/v4/projects/import ``` @@ -168,7 +167,7 @@ requests.post(url, headers=headers, data=data, files=files) Get the status of an import. -```http +```text GET /projects/:id/import ``` @@ -176,7 +175,7 @@ GET /projects/:id/import | --------- | -------------- | -------- | ---------------------------------------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | -```console +```sh curl --header "PRIVATE-TOKEN: " https://gitlab.example.com/api/v4/projects/1/import ``` diff --git a/doc/api/protected_branches.md b/doc/api/protected_branches.md index fa04680d406..a261bb75be5 100644 --- a/doc/api/protected_branches.md +++ b/doc/api/protected_branches.md @@ -5,6 +5,7 @@ **Valid access levels** The access levels are defined in the `ProtectedRefAccess.allowed_access_levels` method. Currently, these levels are recognized: + ``` 0 => No access 30 => Developer access diff --git a/doc/api/releases/index.md b/doc/api/releases/index.md index 61f4ec130fa..e7f79a0d359 100644 --- a/doc/api/releases/index.md +++ b/doc/api/releases/index.md @@ -2,7 +2,7 @@ > - [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/41766) in GitLab 11.7. > - Using this API you can manipulate GitLab's [Release](../../user/project/releases/index.md) entries. -> - For manipulating links as a release asset, see [Release Links API](links.md) +> - For manipulating links as a release asset, see [Release Links API](links.md). ## List Releases diff --git a/doc/api/templates/gitignores.md b/doc/api/templates/gitignores.md index 3804855129c..bf6a914e120 100644 --- a/doc/api/templates/gitignores.md +++ b/doc/api/templates/gitignores.md @@ -1,8 +1,8 @@ -# Gitignores API +# `.gitignore` API -## List gitignore templates +## List `.gitignore` templates -Get all gitignore templates. +Get all `.gitignore` templates. ``` GET /templates/gitignores @@ -99,9 +99,9 @@ Example response: ] ``` -## Single gitignore template +## Single `.gitignore` template -Get a single gitignore template. +Get a single `.gitignore` template. ``` GET /templates/gitignores/:key @@ -109,7 +109,7 @@ GET /templates/gitignores/:key | Attribute | Type | Required | Description | | ---------- | ------ | -------- | ----------- | -| `key` | string | yes | The key of the gitignore template | +| `key` | string | yes | The key of the `.gitignore` template | ```bash curl https://gitlab.example.com/api/v4/templates/gitignores/Ruby -- cgit v1.2.1