[AIRFLOW-XXX] Group references in one section
diff --git a/docs/autoapi_templates/index.rst b/docs/autoapi_templates/index.rst
index 461204b4a2887..4b24a5ce019bf 100644
--- a/docs/autoapi_templates/index.rst
+++ b/docs/autoapi_templates/index.rst
@@ -15,8 +15,8 @@
     specific language governing permissions and limitations
     under the License.
 
-API Reference
-=============
+Python API Reference
+====================
 
 Operators
 ---------
diff --git a/docs/cli.rst b/docs/cli-ref.rst
similarity index 100%
rename from docs/cli.rst
rename to docs/cli-ref.rst
diff --git a/docs/concepts.rst b/docs/concepts.rst
index e060ba559e6f2..db484cde76435 100644
--- a/docs/concepts.rst
+++ b/docs/concepts.rst
@@ -1066,7 +1066,7 @@ Jinja Templating
 
 Airflow leverages the power of
 `Jinja Templating <http://jinja.pocoo.org/docs/dev/>`_ and this can be a
-powerful tool to use in combination with macros (see the :doc:`macros` section).
+powerful tool to use in combination with macros (see the :doc:`macros-ref` section).
 
 For example, say you want to pass the execution date as an environment variable
 to a Bash script using the ``BashOperator``.
diff --git a/docs/howto/operator/python.rst b/docs/howto/operator/python.rst
index da2180138e069..5a615618e7196 100644
--- a/docs/howto/operator/python.rst
+++ b/docs/howto/operator/python.rst
@@ -44,7 +44,7 @@ Templating
 
 When you set the ``provide_context`` argument to ``True``, Airflow passes in
 an additional set of keyword arguments: one for each of the :doc:`Jinja
-template variables <../../macros>` and a ``templates_dict`` argument.
+template variables <../../macros-ref>` and a ``templates_dict`` argument.
 
 The ``templates_dict`` argument is templated, so each value in the dictionary
 is evaluated as a :ref:`Jinja template <jinja-templating>`.
diff --git a/docs/index.rst b/docs/index.rst
index e7ba0e1058c41..3384f255384c1 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -84,13 +84,19 @@ Content
     plugins
     security
     timezone
-    api
+    usage-rest-api
     integration
     metrics
     kubernetes
     lineage
     changelog
     faq
-    cli
-    macros
-    _api/index
+
+.. toctree::
+    :maxdepth: 1
+    :caption: References
+
+    CLI <cli-ref>
+    Macros <macros-ref>
+    Python API <_api/index>
+    REST API <rest-api-ref>
diff --git a/docs/macros.rst b/docs/macros-ref.rst
similarity index 100%
rename from docs/macros.rst
rename to docs/macros-ref.rst
diff --git a/docs/api.rst b/docs/rest-api-ref.rst
similarity index 62%
rename from docs/api.rst
rename to docs/rest-api-ref.rst
index 8ddfa8a4fdac7..1b186e0a1794d 100644
--- a/docs/api.rst
+++ b/docs/rest-api-ref.rst
@@ -15,21 +15,23 @@
     specific language governing permissions and limitations
     under the License.
 
-Experimental Rest API
-=====================
+REST API Reference
+==================
 
-Airflow exposes an experimental Rest API. It is available through the webserver. Endpoints are
-available at /api/experimental/. Please note that we expect the endpoint definitions to change.
+Airflow exposes an REST API. It is available through the webserver. Endpoints are
+available at ``/api/experimental/``.
+
+.. warning::
+
+  The API structure is not stable. We expect the endpoint definitions to change.
 
 Endpoints
 ---------
 
 .. http:post:: /api/experimental/dags/<DAG_ID>/dag_runs
 
-
   Creates a dag_run for a given dag id.
 
-
   **Trigger DAG with config, example:**
 
   .. code-block:: bash
@@ -45,6 +47,7 @@ Endpoints
 
   Returns a list of Dag Runs for a specific DAG ID.
 
+
 .. http:get:: /api/experimental/dags/<string:dag_id>/dag_runs/<string:execution_date>
 
   Returns a JSON with a dag_run's public instance variables. The format for the <string:execution_date> is expected to be "YYYY-mm-DDTHH:MM:SS", for example: "2016-11-16T11:34:15".
@@ -84,60 +87,12 @@ Endpoints
 
   Get pool by a given name.
 
+
 .. http:post:: /api/experimental/pools
 
   Create a pool.
 
+
 .. http:delete:: /api/experimental/pools/<string:name>
 
   Delete pool.
-
-
-CLI
------
-
-For some functions the cli can use the API. To configure the CLI to use the API when available
-configure as follows:
-
-.. code-block:: bash
-
-    [cli]
-    api_client = airflow.api.client.json_client
-    endpoint_url = http://<WEBSERVER>:<PORT>
-
-
-Authentication
---------------
-
-Authentication for the API is handled separately to the Web Authentication. The default is to not
-require any authentication on the API -- i.e. wide open by default. This is not recommended if your
-Airflow webserver is publicly accessible, and you should probably use the deny all backend:
-
-.. code-block:: ini
-
-    [api]
-    auth_backend = airflow.api.auth.backend.deny_all
-
-Two "real" methods for authentication are currently supported for the API.
-
-To enabled Password authentication, set the following in the configuration:
-
-.. code-block:: bash
-
-    [api]
-    auth_backend = airflow.contrib.auth.backends.password_auth
-
-It's usage is similar to the Password Authentication used for the Web interface.
-
-To enable Kerberos authentication, set the following in the configuration:
-
-.. code-block:: ini
-
-    [api]
-    auth_backend = airflow.api.auth.backend.kerberos_auth
-
-    [kerberos]
-    keytab = <KEYTAB>
-
-The Kerberos service is configured as ``airflow/fully.qualified.domainname@REALM``. Make sure this
-principal exists in the keytab file.
diff --git a/docs/tutorial.rst b/docs/tutorial.rst
index 2b1bdb0558949..d319ef23260a1 100644
--- a/docs/tutorial.rst
+++ b/docs/tutorial.rst
@@ -260,7 +260,7 @@ regarding custom filters have a look at the
 `Jinja Documentation <http://jinja.pocoo.org/docs/dev/api/#writing-filters>`_
 
 For more information on the variables and macros that can be referenced
-in templates, make sure to read through the :doc:`macros`
+in templates, make sure to read through the :doc:`macros-ref`
 
 Setting up Dependencies
 -----------------------
diff --git a/docs/usage-rest-api.rst b/docs/usage-rest-api.rst
new file mode 100644
index 0000000000000..6d2074b050cf8
--- /dev/null
+++ b/docs/usage-rest-api.rst
@@ -0,0 +1,74 @@
+..  Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+..    http://www.apache.org/licenses/LICENSE-2.0
+
+..  Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+
+Using the REST API
+==================
+
+This document is meant to give an overview of all common tasks while using an REST API.
+
+.. note::
+
+    API endpoints and samples are described in :doc:`rest-api-ref`.
+
+CLI
+---
+
+For some functions the cli can use the API. To configure the CLI to use the API when available
+configure as follows:
+
+.. code-block:: ini
+
+    [cli]
+    api_client = airflow.api.client.json_client
+    endpoint_url = http://<WEBSERVER>:<PORT>
+
+
+Authentication
+--------------
+
+Authentication for the API is handled separately to the Web Authentication. The default is to not
+require any authentication on the API -- i.e. wide open by default. This is not recommended if your
+Airflow webserver is publicly accessible, and you should probably use the ``deny all`` backend:
+
+.. code-block:: ini
+
+    [api]
+    auth_backend = airflow.api.auth.backend.deny_all
+
+Two "real" methods for authentication are currently supported for the API.
+
+To enabled Password authentication, set the following in the configuration:
+
+.. code-block:: ini
+
+    [api]
+    auth_backend = airflow.contrib.auth.backends.password_auth
+
+It's usage is similar to the Password Authentication used for the Web interface.
+
+To enable Kerberos authentication, set the following in the configuration:
+
+.. code-block:: ini
+
+    [api]
+    auth_backend = airflow.api.auth.backend.kerberos_auth
+
+    [kerberos]
+    keytab = <KEYTAB>
+
+The Kerberos service is configured as ``airflow/fully.qualified.domainname@REALM``. Make sure this
+principal exists in the keytab file.

Preview is available: http://frantic-station.surge.sh/ (10 Aug 2019, 15:26 CEST)

---

Make sure you have checked _all_ steps below.

### Jira

- [ ] My PR addresses the following [Airflow Jira](https://issues.apache.org/jira/browse/AIRFLOW/) issues and references them in the PR title. For example, "\[AIRFLOW-XXX\] My Airflow PR"
  - https://issues.apache.org/jira/browse/AIRFLOW-XXX
  - In case you are fixing a typo in the documentation you can prepend your commit with \[AIRFLOW-XXX\], code changes always need a Jira issue.
  - In case you are proposing a fundamental code change, you need to create an Airflow Improvement Proposal ([AIP](https://cwiki.apache.org/confluence/display/AIRFLOW/Airflow+Improvements+Proposals)).
  - In case you are adding a dependency, check if the license complies with the [ASF 3rd Party License Policy](https://www.apache.org/legal/resolved.html#category-x).

### Description

- [ ] Here are some details about my PR, including screenshots of any UI changes:

### Tests

- [ ] My PR adds the following unit tests __OR__ does not need testing for this extremely good reason:

### Commits

- [ ] My commits all reference Jira issues in their subject lines, and I have squashed multiple commits if they address the same issue. In addition, my commits follow the guidelines from "[How to write a good git commit message](http://chris.beams.io/posts/git-commit/)":
  1. Subject is separated from body by a blank line
  1. Subject is limited to 50 characters (not including Jira issue reference)
  1. Subject does not end with a period
  1. Subject uses the imperative mood ("add", not "adding")
  1. Body wraps at 72 characters
  1. Body explains "what" and "why", not "how"

### Documentation

- [ ] In case of new functionality, my PR adds documentation that describes how to use it.
  - All the public functions and the classes in the PR contain docstrings that explain what it does
  - If you implement backwards incompatible changes, please leave a note in the [Updating.md](https://github.com/apache/airflow/blob/master/UPDATING.md) so we can assign it to a appropriate release

### Code Quality

- [ ] Passes `flake8`
