diff options
author | Filipa Lacerda <filipa@gitlab.com> | 2017-08-04 19:38:37 +0100 |
---|---|---|
committer | Filipa Lacerda <filipa@gitlab.com> | 2017-08-04 19:38:37 +0100 |
commit | e4f8aa719bcde767793a82103f149cd37b4ad14c (patch) | |
tree | 8070383e2618d45907b33909e5f5020f5e92bcec /doc/api/README.md | |
parent | a432ae9d06f7dc28d0825e87bafb33a04ae3cf20 (diff) | |
parent | 017550d482b0035dbec3ae93f8b0c73839772464 (diff) | |
download | gitlab-ce-e4f8aa719bcde767793a82103f149cd37b4ad14c.tar.gz |
Merge branch 'master' into issue-discussions-refactor
* master: (162 commits)
Since mysql is not a priority anymore, test it less
Add container registry and spam logs icons
Fix different Markdown styles
Backport to CE for:
Make new dropdown dividers full width
Bump GITLAB_SHELL_VERSION and GITALY_VERSION to support unhiding refs
Install yarn via apt in update guides
Use long curl options
Remove monkey-patched Array.prototype.first() and last() methods
Openshift Getting Started
35659 Rename Pipelines tab to CI / CD in new navigation
Don't bother going through an entire Banzai pipeline for empty text
Add active state for pipelines settings on old nav
Bump rspec to 3.6.0
Resolve "Specific Async Script Loading by using a Page Variable"
Revert "Merge branch 'rs-warm-capybara-only-in-ci' into 'master'"
another rubocop style fix
Use mixin for new dropdown style
Migrate Repository#last_commit_for_path to Gitaly
Migrate blame loading to Gitaly
...
Diffstat (limited to 'doc/api/README.md')
-rw-r--r-- | doc/api/README.md | 64 |
1 files changed, 33 insertions, 31 deletions
diff --git a/doc/api/README.md b/doc/api/README.md index 1d2226e2ae8..8acb2145f1a 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -43,6 +43,7 @@ following locations: - [Project Access Requests](access_requests.md) - [Project Members](members.md) - [Project Snippets](project_snippets.md) +- [Protected Branches](protected_branches.md) - [Repositories](repositories.md) - [Repository Files](repository_files.md) - [Runners](runners.md) @@ -76,6 +77,38 @@ controller-specific endpoints. GraphQL has a number of benefits: It will co-exist with the current v4 REST API. If we have a v5 API, this should be a compatibility layer on top of GraphQL. +## 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]. For example, the root of the v4 API +is at `/api/v4`. + +For endpoints that require [authentication](#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). + +Example of a valid API request: + +``` +GET /projects?private_token=9koXpg98eAheJpvBs5tK +``` + +Example of a valid API request using cURL and authentication via header: + +```shell +curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects" +``` + +Example of a valid API request using cURL and authentication via a query string: + +```shell +curl "https://gitlab.example.com/api/v4/projects?private_token=9koXpg98eAheJpvBs5tK" +``` + +The API uses JSON to serialize data. You don't need to specify `.json` at the +end of an API URL. + ## Authentication Most API requests require authentication via a session cookie or token. For @@ -206,37 +239,6 @@ GET /projects?private_token=9koXpg98eAheJpvBs5tK&sudo=23 curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "SUDO: 23" "https://gitlab.example.com/api/v4/projects" ``` -## 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]. - -For endpoints that require [authentication](#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). - -Example of a valid API request: - -``` -GET /projects?private_token=9koXpg98eAheJpvBs5tK -``` - -Example of a valid API request using cURL and authentication via header: - -```shell -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects" -``` - -Example of a valid API request using cURL and authentication via a query string: - -```shell -curl "https://gitlab.example.com/api/v4/projects?private_token=9koXpg98eAheJpvBs5tK" -``` - -The API uses JSON to serialize data. You don't need to specify `.json` at the -end of an API URL. - ## Status codes The API is designed to return different status codes according to context and |