kaxil commented on a change in pull request #10548:
URL: https://github.com/apache/airflow/pull/10548#discussion_r476395275
##########
File path: airflow/api_connexion/openapi/v1.yaml
##########
@@ -19,7 +19,148 @@ openapi: 3.0.3
info:
title: "Airflow API (Stable)"
- description: Apache Airflow management API.
+ description: |
+ # Overview
+
+ To enable facilitate management, the Apache Airflow supports a range of
REST API endpoints across its
Review comment:
```suggestion
To facilitate the management, the Apache Airflow supports a range of
REST API endpoints across its
```
##########
File path: airflow/api_connexion/openapi/v1.yaml
##########
@@ -19,7 +19,148 @@ openapi: 3.0.3
info:
title: "Airflow API (Stable)"
- description: Apache Airflow management API.
+ description: |
+ # Overview
+
+ To enable 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 hearders 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: `jobGroups`.
+
+ 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.
+ - Resource names are consistent between URL parameter 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 pass an credentials data.
+
+ For e.g., here is how to pause a DAG with [curl](https://curl.haxx.se/),
when basic authroization is used:
Review comment:
```suggestion
For e.g., here is how to pause a DAG with [curl](https://curl.haxx.se/),
when basic authorization is used:
```
##########
File path: airflow/api_connexion/openapi/v1.yaml
##########
@@ -19,7 +19,148 @@ openapi: 3.0.3
info:
title: "Airflow API (Stable)"
- description: Apache Airflow management API.
+ description: |
+ # Overview
+
+ To enable 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 hearders 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: `jobGroups`.
+
+ Resource names are used as part of endpoint URLs, as well as in API
parameters and responses.
Review comment:
```suggestion
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: `jobGroups`.
Resource names are used as part of endpoint URLs, as well as in API
parameters and responses.
```
##########
File path: airflow/api_connexion/openapi/v1.yaml
##########
@@ -19,7 +19,148 @@ openapi: 3.0.3
info:
title: "Airflow API (Stable)"
- description: Apache Airflow management API.
+ description: |
+ # Overview
+
+ To enable 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 hearders to your
request:
Review comment:
```suggestion
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:
```
##########
File path: airflow/api_connexion/openapi/v1.yaml
##########
@@ -19,7 +19,148 @@ openapi: 3.0.3
info:
title: "Airflow API (Stable)"
- description: Apache Airflow management API.
+ description: |
+ # Overview
+
+ To enable 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 hearders 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: `jobGroups`.
+
+ 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.
+ - Resource names are consistent between URL parameter 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 pass an credentials data.
+
+ For e.g., here is how to pause a DAG with [curl](https://curl.haxx.se/),
when basic authroization is used:
+ ```bash
+ curl -X POST 'https://example.com/api/v1/dags/{dag_id}' \
+ -H 'Content-Type: application/json' \
+ --user "username:password" \
+ -d '{
+ "is_paused": true,
+ "update_mask": "is_paused"
+ }'
+ ```
+
+ 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 by the most demanding users.
Review comment:
```suggestion
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.
```
##########
File path: airflow/api_connexion/openapi/v1.yaml
##########
@@ -19,7 +19,148 @@ openapi: 3.0.3
info:
title: "Airflow API (Stable)"
- description: Apache Airflow management API.
+ description: |
+ # Overview
+
+ To enable 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 hearders 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: `jobGroups`.
+
+ 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.
+ - Resource names are consistent between URL parameter 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 pass an credentials data.
Review comment:
```suggestion
Note that you will need to pass credentials data.
```
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
[email protected]
