summaryrefslogtreecommitdiff
path: root/doc/api
diff options
context:
space:
mode:
authorEvan Read <eread@gitlab.com>2019-02-15 09:39:23 +0000
committerAchilleas Pipinellis <axil@gitlab.com>2019-02-15 09:39:23 +0000
commitfb6e59ebe34f4c51c212ce0587a9a48066081fd7 (patch)
tree7cc3516bd063f52535a9d019b3cd3c900a1141cb /doc/api
parent2a5de7e0eea45f55aa3dbff789a553eb560375b4 (diff)
downloadgitlab-ce-fb6e59ebe34f4c51c212ce0587a9a48066081fd7.tar.gz
Refactor of API landing page
- Breaks up into more sections. - Also minor fixes to pages within sections.
Diffstat (limited to 'doc/api')
-rw-r--r--doc/api/README.md205
-rw-r--r--doc/api/lint.md2
-rw-r--r--doc/api/pages_domains.md12
-rw-r--r--doc/api/project_import_export.md27
-rw-r--r--doc/api/protected_branches.md1
-rw-r--r--doc/api/releases/index.md2
-rw-r--r--doc/api/templates/gitignores.md12
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: <your_access_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: <your_access_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: <your_access_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: <your_access_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: <your_access_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: <your_access_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: <your_access_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: <your_access_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: <your_access_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: <your_access_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: <your_access_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