Skip to content
Snippets Groups Projects
Commit fb6e59eb authored by Evan Read's avatar Evan Read Committed by Achilleas Pipinellis
Browse files

Refactor of API landing page 

- Breaks up into more sections.
- Also minor fixes to pages within sections.
parent 2a5de7e0
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
doc/api/README.md
+ 122
− 83
View file @ fb6e59eb
# 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
doc/api/lint.md
+ 1
− 1
View file @ fb6e59eb
@@ -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
doc/api/pages_domains.md
+ 6
− 6
View file @ fb6e59eb
@@ -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
```
 
doc/api/project_import_export.md
+ 13
− 14
View file @ fb6e59eb
# 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
```
 
doc/api/protected_branches.md
+ 1
− 0
View file @ fb6e59eb
@@ -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
doc/api/releases/index.md
+ 1
− 1
View file @ fb6e59eb
@@ -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
 
doc/api/templates/gitignores.md
+ 6
− 6
View file @ fb6e59eb
# 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
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment