diff options
Diffstat (limited to 'doc/api/README.md')
| -rw-r--r-- | doc/api/README.md | 110 |
1 files changed, 66 insertions, 44 deletions
diff --git a/doc/api/README.md b/doc/api/README.md index 27c5962decf..288f7f9ee69 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -8,42 +8,49 @@ under [`/lib/api`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/api). Documentation for various API resources can be found separately in the following locations: -- [Users](users.md) -- [Session](session.md) -- [Projects](projects.md) including setting Webhooks -- [Project Snippets](project_snippets.md) -- [Services](services.md) -- [Repositories](repositories.md) -- [Repository Files](repository_files.md) -- [Commits](commits.md) -- [Tags](tags.md) +- [Award Emoji](award_emoji.md) - [Branches](branches.md) -- [Merge Requests](merge_requests.md) +- [Builds](builds.md) +- [Build triggers](build_triggers.md) +- [Build Variables](build_variables.md) +- [Commits](commits.md) +- [Deploy Keys](deploy_keys.md) +- [Groups](groups.md) - [Issues](issues.md) +- [Keys](keys.md) - [Labels](labels.md) +- [Merge Requests](merge_requests.md) - [Milestones](milestones.md) -- [Notes](notes.md) (comments) -- [Deploy Keys](deploy_keys.md) -- [System Hooks](system_hooks.md) -- [Groups](groups.md) +- [Open source license templates](licenses.md) - [Namespaces](namespaces.md) -- [Settings](settings.md) -- [Keys](keys.md) -- [Builds](builds.md) -- [Build triggers](build_triggers.md) -- [Build Variables](build_variables.md) +- [Notes](notes.md) (comments) +- [Projects](projects.md) including setting Webhooks +- [Project Snippets](project_snippets.md) +- [Repositories](repositories.md) +- [Repository Files](repository_files.md) - [Runners](runners.md) -- [Open source license templates](licenses.md) +- [Services](services.md) +- [Session](session.md) +- [Settings](settings.md) +- [Sidekiq metrics](sidekiq_metrics.md) +- [System Hooks](system_hooks.md) +- [Tags](tags.md) +- [Users](users.md) + +### Internal CI API + +The following documentation is for the [internal CI API](ci/README.md): + +- [Builds](ci/builds.md) +- [Runners](ci/runners.md) ## Authentication -All API requests require authentication. You need to pass a `private_token` -parameter via query string or header. If passed as a header, the header name -must be `PRIVATE-TOKEN` (uppercase and with a dash instead of an underscore). -You can find or reset your private token in your account page (`/profile/account`). +All API requests require authentication via a token. There are three types of tokens +available: private tokens, OAuth 2 tokens, and personal access tokens. -If `private_token` is invalid or omitted, then an error message will be -returned with status code `401`: +If a token is invalid or omitted, an error message will be returned with +status code `401`: ```json { @@ -51,42 +58,56 @@ returned with status code `401`: } ``` -API requests should be prefixed with `api` and the API version. The API version -is defined in [`lib/api.rb`][lib-api-url]. +### Private Tokens -Example of a valid API request: +You need to pass a `private_token` parameter via query string or header. If passed as a +header, the header name must be `PRIVATE-TOKEN` (uppercase and with a dash instead of +an underscore). You can find or reset your private token in your account page +(`/profile/account`). -```shell -GET https://gitlab.example.com/api/v3/projects?private_token=9koXpg98eAheJpvBs5tK -``` +### OAuth 2 Tokens -Example of a valid API request using cURL and authentication via header: +You can use an OAuth 2 token to authenticate with the API by passing it either in the +`access_token` parameter or in the `Authorization` header. + +Example of using the OAuth2 token in the header: ```shell -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects" +curl -H "Authorization: Bearer OAUTH-TOKEN" https://gitlab.example.com/api/v3/projects ``` -The API uses JSON to serialize data. You don't need to specify `.json` at the -end of an API URL. +Read more about [GitLab as an OAuth2 client](oauth2.md). + +### Personal Access Tokens -## Authentication with OAuth2 token +> **Note:** This feature was [introduced][ce-3749] in GitLab 8.8 -Instead of the `private_token` you can transmit the OAuth2 access token as a -header or as a parameter. +You can create as many personal access tokens as you like from your GitLab +profile (`/profile/personal_access_tokens`); perhaps one for each application +that needs access to the GitLab API. -Example of OAuth2 token as a parameter: +Once you have your token, pass it to the API using either the `private_token` +parameter or the `PRIVATE-TOKEN` header. + +## Basic Usage + +API requests should be prefixed with `api` and the API version. The API version +is defined in [`lib/api.rb`][lib-api-url]. + +Example of a valid API request: ```shell -curl https://gitlab.example.com/api/v3/user?access_token=OAUTH-TOKEN +GET https://gitlab.example.com/api/v3/projects?private_token=9koXpg98eAheJpvBs5tK ``` -Example of OAuth2 token as a header: +Example of a valid API request using cURL and authentication via header: ```shell -curl -H "Authorization: Bearer OAUTH-TOKEN" https://example.com/api/v3/user +curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects" ``` -Read more about [GitLab as an OAuth2 client](oauth2.md). +The API uses JSON to serialize data. You don't need to specify `.json` at the +end of an API URL. ## Status codes @@ -323,3 +344,4 @@ programming languages. Visit the [GitLab website] for a complete list. [GitLab website]: https://about.gitlab.com/applications/#api-clients "Clients using the GitLab API" [lib-api-url]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/api/api.rb +[ce-3749]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3749 |