You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@airflow.apache.org by GitBox <gi...@apache.org> on 2020/08/25 11:59:07 UTC
[GitHub] [airflow] mik-laj opened a new pull request #10548: Add introduction to Stable RESTT API
mik-laj opened a new pull request #10548:
URL: https://github.com/apache/airflow/pull/10548
<!--
Thank you for contributing! Please make sure that your code changes
are covered with tests. And in case of new features or big changes
remember to adjust the documentation.
Feel free to ping committers for the review!
In case of existing issue, reference it using one of the following:
closes: #ISSUE
related: #ISSUE
How to write a good git commit message:
http://chris.beams.io/posts/git-commit/
-->
---
**^ Add meaningful description above**
Read the **[Pull Request Guidelines](https://github.com/apache/airflow/blob/master/CONTRIBUTING.rst#pull-request-guidelines)** for more information.
In case of fundamental code change, Airflow Improvement Proposal ([AIP](https://cwiki.apache.org/confluence/display/AIRFLOW/Airflow+Improvements+Proposals)) is needed.
In case of a new dependency, check compliance with the [ASF 3rd Party License Policy](https://www.apache.org/legal/resolved.html#category-x).
In case of backwards incompatible changes please leave a note in [UPDATING.md](https://github.com/apache/airflow/blob/master/UPDATING.md).
----------------------------------------------------------------
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:
users@infra.apache.org
[GitHub] [airflow] kaxil commented on a change in pull request #10548: Add introduction to Stable RESTT API
Posted by GitBox <gi...@apache.org>.
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:
users@infra.apache.org
[GitHub] [airflow] mik-laj merged pull request #10548: Add introduction to Stable RESTT API
Posted by GitBox <gi...@apache.org>.
mik-laj merged pull request #10548:
URL: https://github.com/apache/airflow/pull/10548
----------------------------------------------------------------
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:
users@infra.apache.org
[GitHub] [airflow] mik-laj commented on pull request #10548: Add introduction to Stable RESTT API
Posted by GitBox <gi...@apache.org>.
mik-laj commented on pull request #10548:
URL: https://github.com/apache/airflow/pull/10548#issuecomment-680000895
@kaxil All suggestion accepted.
----------------------------------------------------------------
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:
users@infra.apache.org