Add introduction to Stable RESTT API (apache#10548)

airflow/api_connexion/openapi/v1.yaml

@@ -19,7 +19,147 @@ openapi: 3.0.3
 
 info:
   title: "Airflow API (Stable)"
-  description: Apache Airflow management API.
+  description: |
+    # Overview
+
+    To facilitate management, the Apache Airflow supports a range of REST API endpoints across its
+    objects.
+    This section provides an overview of the API design, methods, and supported use cases.
+
+    Most of the endpoints accept `JSON` as input and return `JSON` responses.
+    This means that you must usually add the following headers to your request:
+    ```
+    Content-type: application/json
+    Accept: application/json
+    ```
+
+    ## Resources
+
+    The term `resource` refers to a single type of object in the Airflow metadata. An API is broken up by its
+    endpoint's corresponding resource.
+    The name of a resource is typically plural and expressed in camelCase. Example: `dagRuns`.
+
+    Resource names are used as part of endpoint URLs, as well as in API parameters and responses.
+
+    ## CRUD Operations
+
+    The platform supports **C**reate, **R**ead, **U**pdate, and **D**elete operations on most resources.
+    You can review the standards for these operations and their standard parameters below.
+
+    Some endpoints have special behavior as exceptions.
+
+    ### Create
+
+    To create a resource, you typically submit an HTTP `POST` request with the resource's required metadata
+    in the request body.
+    The response returns a `201 Created` response code upon success with the resource's metadata, including
+    its internal `id`, in the response body.
+
+    ### Read
+
+    An HTTP `GET` request can be used to read a resource or to list a number of resources.
+
+    A resource's `id` can be submitted in the request parameters to read a specific resource.
+    The response usually returns a `200 OK` response code upon success, with the resource's metadata in
+    the response body.
+
+    If a `GET` request does not include a specific resource `id`, it is treated as a list request.
+    The response usually returns a `200 OK` response code upon success, with an object containing a list
+    of resources' metadata in the response body.
+
+    When reading resources, some common query parameters are usually available. e.g.:
+    ```
+    v1/connections?limit=25&offset=25
+    ```
+
+    |Query Parameter|Type|Description|
+    |---------------|----|-----------|
+    |limit|integer|Maximum number of objects to fetch. Usually 25 by default|
+    |offset|integer|Offset after which to start returning objects. For use with limit query parameter.|
+
+    ### Update
+
+    Updating a resource requires the resource `id`, and is typically done using an HTTP `PATCH` request,
+    with the fields to modify in the request body.
+    The response usually returns a `200 OK` response code upon success, with information about the modified
+    resource in the response body.
+
+    ### Delete
+
+    Deleting a resource requires the resource `id` and is typically executing via an HTTP `DELETE` request.
+    The response usually returns a `204 No Content` response code upon success.
+
+    ## Conventions
+    - Resource names are plural and expressed in camelCase.
+    - Names are consistent between URL parameter name and field name.
+
+    - Field names are in snake_case.
+    ```json
+    {
+        "name": "string",
+        "slots": 0,
+        "occupied_slots": 0,
+        "used_slots": 0,
+        "queued_slots": 0,
+        "open_slots": 0
+    }
+    ```
+
+
+    ## Versioning and Endpoint Lifecycle
+
+    - API versioning is not synchronized to specific releases of the Apache Airflow.
+    - APIs are designed to be backward compatible.
+    - Any changes to the API will first go through a deprecation phase.
+
+    # Summary of Changes
+
+    | Airflow version | Description |
+    |-|-|
+    | v2.0 | Initial releaase |
+
+    # Trying the API
+    You can use a third party client, such as [curl](https://curl.haxx.se/), [HTTPie](https://httpie.org/),
+    [Postman](https://www.postman.com/) or the [Insomnia rest client](https://insomnia.rest/) to test
+    the Apache Airflow API.
+
+    Note that you will need to passcredentials data.
+
+    For e.g., here is how to pause a DAG with [curl](https://curl.haxx.se/), when basic authorization is used:
+    ```bash
+    curl -X POST 'https://example.com/api/v1/dags/{dag_id}?update_mask=is_paused' \
+    -H 'Content-Type: application/json' \
+    --user "username:password" \
+    -d '{
+        "is_paused": true
+    }'
+    ```
+
+    Using a graphical tool such as [Postman](https://www.postman.com/) or [Insomnia](https://insomnia.rest/),
+    it is possible to import the API specifications directly:
+    1. Download the API specification by clicking the **Download** button at top of this document
+    2. Import the JSON specification in the graphical tool of your choice.
+      - In *Postman*, you can click the **import** button at the top
+      - With *Insomnia*, you can just drag-and-drop the file on the UI
+
+    Note that with *Postman*, you can also generate code snippets by selecting a request and clicking on
+    the **Code** button.
+
+    # Authentication
+
+    To be able to meet the requirements of many organizations, Airflow supports many authentication methods,
+    and it is even possible to add your own method.
+
+    If you want to check which executor is currently set, you can use
+    `airflow config get-value api auth_backend` command as in the example below.
+    ```bash
+    $ airflow config get-value api auth_backend
+    airflow.api.auth.backend.basic_auth
+    ```
+    The default is to deny all requests.
+
+    For details on configuring the authentication, see
+    [API Authorization](https://airflow.readthedocs.io/en/latest/security/api.html).
   version: '1.0.0'
   license:
     name: Apache 2.0

docs/security/api.rst

@@ -38,6 +38,17 @@ deny all requests:
     In Airflow <1.10.11, the default setting was to allow all API requests without authentication, but this
     posed security risks for if the Webserver is publicly accessible.
 
+If you want to check which executor is currently set, you can use ``airflow config get-value api auth_backend``
+command as in the example below.
+
+.. code-block:: console
+
+    $ airflow config get-value api auth_backend
+    airflow.api.auth.backend.basic_auth
+
+Disable authorization
+'''''''''''''''''''''
+
 If you wish to have the experimental API work, and aware of the risks of enabling this without authentication
 (or if you have your own authentication layer in front of Airflow) you can set the following in ``airflow.cfg``: