summaryrefslogtreecommitdiff
path: root/doc/api/README.md
diff options
context:
space:
mode:
authorFilipa Lacerda <filipa@gitlab.com>2017-08-04 19:38:37 +0100
committerFilipa Lacerda <filipa@gitlab.com>2017-08-04 19:38:37 +0100
commite4f8aa719bcde767793a82103f149cd37b4ad14c (patch)
tree8070383e2618d45907b33909e5f5020f5e92bcec /doc/api/README.md
parenta432ae9d06f7dc28d0825e87bafb33a04ae3cf20 (diff)
parent017550d482b0035dbec3ae93f8b0c73839772464 (diff)
downloadgitlab-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.md64
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