You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@airflow.apache.org by ka...@apache.org on 2020/08/03 10:29:03 UTC
[airflow] branch master updated: Move stable REST API migration
guide to UPDATING.md (#10098)
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 d0776cf Move stable REST API migration guide to UPDATING.md (#10098)
d0776cf is described below
commit d0776cf40650f56330692d182408c65d893b76c1
Author: Ephraim Anierobi <sp...@gmail.com>
AuthorDate: Mon Aug 3 11:28:16 2020 +0100
Move stable REST API migration guide to UPDATING.md (#10098)
---
UPDATING.md | 40 ++++++++
docs/index.rst | 1 -
docs/rest-api-ref.rst | 2 +-
docs/stable-rest-api/migration.rst | 181 -------------------------------------
4 files changed, 41 insertions(+), 183 deletions(-)
diff --git a/UPDATING.md b/UPDATING.md
index 50fd686..404e265 100644
--- a/UPDATING.md
+++ b/UPDATING.md
@@ -136,6 +136,46 @@ with third party services to the ``airflow.providers`` package.
All changes made are backward compatible, but if you use the old import paths you will
see a deprecation warning. The old import paths can be abandoned in the future.
+### Migration Guide from Experimental API to Stable API v1
+In Airflow 2.0, we added the new REST API. Experimental API still works, but support may be dropped in the future.
+If your application is still using the experimental API, you should consider migrating to the stable API.
+
+The stable API exposes many endpoints available through the webserver. Here are the
+differences between the two endpoints that will help you migrate from the
+experimental REST API to the stable REST API.
+
+#### Base Endpoint
+The base endpoint for the stable API v1 is ``/api/v1/``. You must change the
+experimental base endpoint from ``/api/experimental/`` to ``/api/v1/``.
+The table below shows the differences:
+
+| Purpose | Experimental REST API Endpoint | Stable REST API Endpoint |
+|-----------------------------------|----------------------------------------------------------------------------------|--------------------------------------------------------------------------------|
+| Create a DAGRuns(POST) | /api/experimental/dags/<DAG_ID>/dag_runs | /api/v1/dags/{dag_id}/dagRuns |
+| List DAGRuns(GET) | /api/experimental/dags/<DAG_ID>/dag_runs | /api/v1/dags/{dag_id}/dagRuns |
+| Check Health status(GET) | /api/experimental/test | /api/v1/health |
+| Task information(GET) | /api/experimental/dags/<DAG_ID>/tasks/<TASK_ID> | /api/v1//dags/{dag_id}/tasks/{task_id} |
+| TaskInstance public variable(GET) | /api/experimental/dags/<DAG_ID>/dag_runs/<string:execution_date>/tasks/<TASK_ID> | /api/v1/dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances/{task_id} |
+| Pause DAG(PATCH) | /api/experimental/dags/<DAG_ID>/paused/<string:paused> | /api/v1/dags/{dag_id} |
+| Information of paused DAG(GET) | /api/experimental/dags/<DAG_ID>/paused | /api/v1/dags/{dag_id} |
+| Latest DAG Runs(GET) | /api/experimental/latest_runs | /api/v1/dags/{dag_id}/dagRuns |
+| Get all pools(GET) | /api/experimental/pools | /api/v1/pools |
+| Create a pool(POST) | /api/experimental/pools | /api/v1/pools |
+| Delete a pool(DELETE) | /api/experimental/pools/<string:name> | /api/v1/pools/{pool_name} |
+| DAG Lineage(GET) | /api/experimental/lineage/<DAG_ID>/<string:execution_date>/ | /api/v1/dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances/{task_id}/xcomEntries |
+
+#### Note
+This endpoint ``/api/v1/dags/{dag_id}/dagRuns`` also allows you to filter dag_runs with parameters such as ``start_date``, ``end_date``, ``execution_date`` etc in the query string.
+Therefore the operation previously performed by this endpoint
+
+ /api/experimental/dags/<string:dag_id>/dag_runs/<string:execution_date>
+
+can now be handled with filter parameters in the query string.
+Getting information about latest runs can be accomplished with the help of
+filters in the query string of this endpoint(``/api/v1/dags/{dag_id}/dagRuns``). Please check the Stable API
+reference documentation for more information
+
+
### CLI changes in Airflow 2.0
The Airflow CLI has been organized so that related commands are grouped together as subcommands,
diff --git a/docs/index.rst b/docs/index.rst
index 7bc223d..41d014f 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -96,7 +96,6 @@ Content
lineage
dag-serialization
Using the REST API <stable-rest-api/index>
- REST API Migration Guide <stable-rest-api/migration>
changelog
best-practices
faq
diff --git a/docs/rest-api-ref.rst b/docs/rest-api-ref.rst
index 8719965..11f93f8 100644
--- a/docs/rest-api-ref.rst
+++ b/docs/rest-api-ref.rst
@@ -24,7 +24,7 @@ available at ``/api/experimental/``.
.. warning::
This REST API is deprecated since version 2.0. Please consider using :doc:`the stable REST API <stable-rest-api/redoc>`.
- For more information on migration, see: :doc:`stable-rest-api/migration`.
+ For more information on migration, see `UPDATING.md <https://github.com/apache/airflow/blob/master/UPDATING.md>`_
Endpoints
---------
diff --git a/docs/stable-rest-api/migration.rst b/docs/stable-rest-api/migration.rst
deleted file mode 100644
index cd690d5..0000000
--- a/docs/stable-rest-api/migration.rst
+++ /dev/null
@@ -1,181 +0,0 @@
- .. 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.
-
-Migration Guide from Experimental API to Stable API v1
-======================================================
-This article provides guidelines for migrating from experimental REST API to the
-stable REST API.
-
-Introduction
-------------
-If your application is still using the experimental API, it is important to
-consider migrating to the stable API so that your application continues to
-work.
-
-The stable API exposes many endpoints available through the webserver. Here are the
-differences between the two endpoints that will help you migrate from the
-experimental REST API to the stable REST API.
-
-Base Endpoint
-^^^^^^^^^^^^^
-The base endpoint for the stable API v1 is ``/api/v1/``. You must change the
-experimental base endpoint from ``/api/experimental/`` to ``/api/v1/``.
-
-Create a dag_run from a given dag_id
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The endpoint for creating a dag_run from a given dag_id has changed from
-
-.. http:post:: /api/experimental/dags/<DAG_ID>/dag_runs
-
-to
-
-.. http:post:: /api/v1/dags/{dag_id}/dagRuns
-
-
-List dag_runs from a specific DAG ID
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The endpoint to get the list of dag_runs for a specific dag_id has changed from
-
-.. http:get:: /api/experimental/dags/<DAG_ID>/dag_runs
-
-to
-
-.. http:get:: /api/v1/dags/{dag_id}/dagRuns
-
-This endpoint also allows you to filter dag_runs with parameters such as ``start_date``, ``end_date``, ``execution_date`` etc in the query string.
-Therefore the operation previously performed by this endpoint
-
-.. http:get:: /api/experimental/dags/<string:dag_id>/dag_runs/<string:execution_date>
-
-can now be handled with filter parameters in the query string.
-
-Health endpoint
-^^^^^^^^^^^^^^^
-The operation previously performed in the experimental REST API endpoint to check
-the health status has changed from
-
-.. http:get:: /api/experimental/test
-
-to
-
-.. http:get:: /api/v1/health
-
-Task information endpoint
-^^^^^^^^^^^^^^^^^^^^^^^^^
-The endpoint for getting task information has changed from
-
-.. http:get:: /api/experimental/dags/<DAG_ID>/tasks/<TASK_ID>
-
-to
-
-.. http:get:: /api/v1//dags/{dag_id}/tasks/{task_id}
-
-Task Instance
-^^^^^^^^^^^^^
-The endpoint for getting task instance's public instance variable
-has changed from
-
-.. http:get:: /api/experimental/dags/<DAG_ID>/dag_runs/<string:execution_date>/tasks/<TASK_ID>
-
-to
-
-.. http:get:: /api/v1/dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances/{task_id}
-
-
-DAG
-^^^
-The endpoint for pausing a dag has changed from
-
-.. http:get:: /api/experimental/dags/<DAG_ID>/paused/<string:paused>
-
-to
-
-.. http:patch:: /api/v1/dags/{dag_id}
-
-while getting information about the paused state of a dag has changed from
-
-.. http:get:: /api/experimental/dags/<DAG_ID>/paused
-
-to
-
-.. http:get:: /api/v1/dags/{dag_id}
-
-
-Latest DAG Runs
-^^^^^^^^^^^^^^^
-The endpoint for getting the latest DagRun for each DAG formatted for the UI
-have changed from
-
-.. http:get:: /api/experimental/latest_runs
-
-to
-
-.. http:get:: /api/v1/dags/{dag_id}/dagRuns
-
-Getting information about latest runs can be accomplished with the help of
-filters in the query string of this endpoint. Please check the Stable API
-reference documentation for more information
-
-Get all Pools
-^^^^^^^^^^^^^
-The endpoint for getting all pools has changed from
-
-.. http:get:: /api/experimental/pools
-
-to
-
-.. http:get:: /api/v1/pools
-
-Get pool by a given name
-^^^^^^^^^^^^^^^^^^^^^^^^
-The endpoint to get pool by a given name has changed from
-
-.. http:get:: /api/experimental/pools/<string:name>
-
-to
-
-.. http:get:: /api/v1/pools/{pool_name}
-
-Create a Pool
-^^^^^^^^^^^^^
-The endpoint for creating a pool has changed from
-
-.. http:post:: /api/experimental/pools
-
-to
-
-.. http:post:: /api/v1/pools
-
-Delete a Pool
-^^^^^^^^^^^^^
-The endpoint for deleting a pool has changed from
-
-.. http:delete:: /api/experimental/pools/<string:name>
-
-to
-
-.. http:delete:: /api/v1/pools/{pool_name}
-
-DAG Lineage
-^^^^^^^^^^^
-The endpoint for returning the lineage of a dag have changed from
-
-.. http:get:: /api/experimental/lineage/<DAG_ID>/<string:execution_date>/
-
-to
-
-.. http:get:: /api/v1/dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances/{task_id}/xcomEntries