This is an automated email from the ASF dual-hosted git repository.
kamilbregula pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/master by this push:
new 5e82263 Add introduction to Stable RESTT API (#10548)
5e82263 is described below
commit 5e822634de94ca516818cababc592d38dc882d46
Author: Kamil BreguĊa <[email protected]>
AuthorDate: Tue Aug 25 15:10:22 2020 +0200
Add introduction to Stable RESTT API (#10548)
---
airflow/api_connexion/openapi/v1.yaml | 142 +++++++++++++++++++++++++++++++++-
docs/security/api.rst | 11 +++
2 files changed, 152 insertions(+), 1 deletion(-)
diff --git a/airflow/api_connexion/openapi/v1.yaml
b/airflow/api_connexion/openapi/v1.yaml
index 7970538..205cd29 100644
--- a/airflow/api_connexion/openapi/v1.yaml
+++ b/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
diff --git a/docs/security/api.rst b/docs/security/api.rst
index e225ee9..adb35fd 100644
--- a/docs/security/api.rst
+++ b/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``:
