From a2ac5720ef982b9ed1012e9b64ab36679a303c52 Mon Sep 17 00:00:00 2001
From: AJ Jordan <alex@strugee.net>
Date: Fri, 28 Jul 2017 21:19:05 +0000
Subject: [PATCH 1/2] Move API "basic usage" to be more visible

---
 doc/api/README.md | 62 +++++++++++++++++++++++------------------------
 1 file changed, 31 insertions(+), 31 deletions(-)

diff --git a/doc/api/README.md b/doc/api/README.md
index fe29563eaca..b16f31306a8 100644
--- a/doc/api/README.md
+++ b/doc/api/README.md
@@ -75,6 +75,37 @@ 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 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
@@ -205,37 +236,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

From 97f58c78311c453a40498e74114817ffc6f79476 Mon Sep 17 00:00:00 2001
From: AJ Jordan <alex@strugee.net>
Date: Fri, 28 Jul 2017 14:30:42 -0700
Subject: [PATCH 2/2] Explicitly spell out where the API root is

I found this basic information extrememly hard to find when I looked
at this page.
---
 doc/api/README.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/doc/api/README.md b/doc/api/README.md
index b16f31306a8..cb4ec88e868 100644
--- a/doc/api/README.md
+++ b/doc/api/README.md
@@ -78,7 +78,8 @@ 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].
+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,