From c32239a5cdd0d7991a4c6782b3bc80d6e3ed7746 Mon Sep 17 00:00:00 2001 From: EphraimBuddy Date: Sat, 11 Jul 2020 22:17:50 +0100 Subject: [PATCH 1/5] Add stable API migration guide --- docs/index.rst | 1 + docs/stable-rest-api/migration.rst | 180 +++++++++++++++++++++++++++++ 2 files changed, 181 insertions(+) create mode 100644 docs/stable-rest-api/migration.rst diff --git a/docs/index.rst b/docs/index.rst index d3282dc7b0011..c7ed4236e0904 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -96,6 +96,7 @@ Content lineage dag-serialization Using the REST API + REST API Migration Guide changelog best-practices faq diff --git a/docs/stable-rest-api/migration.rst b/docs/stable-rest-api/migration.rst new file mode 100644 index 0000000000000..e5ce9e35c37ed --- /dev/null +++ b/docs/stable-rest-api/migration.rst @@ -0,0 +1,180 @@ + .. 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 in migrating 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 have changed from + +.. http:post:: /api/experimental/dags//dag_runs + +to + +.. http:post:: /api/v1/dags/{dag_id}/dagRuns + + +List dag_runs from a specific DAG ID +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The endpoint to get list of dag_runs for a specific dag_id have changed from + +.. http:get:: /api/experimental/dags//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//dag_runs/ + +can now be handled with filter parameters in the query string. Please check the +reference documentaion for more information + +Health endpoint +^^^^^^^^^^^^^^^ +The operation previously performed in the experimental REST API endpoint to check +the health status have changed from + +.. http:get:: /api/experimental/test + +to + +.. http:get:: /api/v1/health + +Task information endpoint +^^^^^^^^^^^^^^^^^^^^^^^^^ +The endpoint for getting a task information have changed from + +.. http:get:: /api/experimental/dags//tasks/ + +to + +.. http:get:: /api/v1//dags/{dag_id}/tasks/{task_id} + +Task Instance +^^^^^^^^^^^^^ +The endpoint for getting task instance`s public instance variable +have changed from + +.. http:get:: /api/experimental/dags//dag_runs//tasks/ + +to + +.. http:get:: /api/v1/dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances/{task_id} + +Please check the Stable API reference documentaion for more information + +DAG +^^^ +The endpoint for pausing a dag have changed from + +.. http:get:: /api/experimental/dags//paused/ + +to + +.. http:patch:: /api/v1/dags/{dag_id} + +while getting information about the paused state of a dag have changed from + +.. http:get:: /api/experimental/dags//paused + +to + +.. http:get:: /api/v1/dags/{dag_id} + +Please check the Stable API reference documentaion for more information + +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 have 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 have changed from + +.. http:get:: /api/experimental/pools/ + +to + +.. http:get:: /api/v1/pools/{pool_name} + +Create a pool +^^^^^^^^^^^^^ +The endpoint for creating a pool have changed from + +.. http:post:: /api/experimental/pools + +to + +.. http:post:: /api/v1/pools + +Delete a pool +^^^^^^^^^^^^^ +The endpoint for deleting a pool have changed from + +.. http:delete:: /api/experimental/pools/ + +to + +.. http:delete:: /api/v1/pools/{pool_name} + +Lineage of a DAG +^^^^^^^^^^^^^^^^ +We currently do not have endpoint for the lineage of a DAG in the stable +API From 05d211c16d144f45b5aa99ddecba02afa640c185 Mon Sep 17 00:00:00 2001 From: EphraimBuddy Date: Sun, 12 Jul 2020 00:15:27 +0100 Subject: [PATCH 2/5] fixup! Add stable API migration guide --- docs/stable-rest-api/migration.rst | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/stable-rest-api/migration.rst b/docs/stable-rest-api/migration.rst index e5ce9e35c37ed..b6c4339bb0b8e 100644 --- a/docs/stable-rest-api/migration.rst +++ b/docs/stable-rest-api/migration.rst @@ -176,5 +176,13 @@ to Lineage of a DAG ^^^^^^^^^^^^^^^^ -We currently do not have endpoint for the lineage of a DAG in the stable -API +The endpoint for returning the lineage of a dag have changed from + +.. http:get:: /api/experimental/lineage/// + +to + +.. http:get:: /api/v1/dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances/{task_id}/xcomEntries + +More information about using this endpoint can be found in the stable REST API +documentation From 7464ea6e324e4fa47d107c4a3613fbbcabdcfe4e Mon Sep 17 00:00:00 2001 From: Ephraim Anierobi Date: Sun, 12 Jul 2020 00:34:39 +0100 Subject: [PATCH 3/5] Apply suggestions from code review Co-authored-by: Kaxil Naik --- docs/stable-rest-api/migration.rst | 37 +++++++++++++++--------------- 1 file changed, 18 insertions(+), 19 deletions(-) diff --git a/docs/stable-rest-api/migration.rst b/docs/stable-rest-api/migration.rst index b6c4339bb0b8e..9d609b7a5784b 100644 --- a/docs/stable-rest-api/migration.rst +++ b/docs/stable-rest-api/migration.rst @@ -15,7 +15,7 @@ specific language governing permissions and limitations under the License. -MIGRATION GUIDE FROM EXPERIMENTAL API TO STABLE API v1 +Migration Guide from Experimental API to Stable API v1 ====================================================== This article provides guidelines for migrating from experimental REST API to the stable REST API. @@ -37,7 +37,7 @@ 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 have changed from +The endpoint for creating a dag_run from a given dag_id has changed from .. http:post:: /api/experimental/dags//dag_runs @@ -48,7 +48,7 @@ to List dag_runs from a specific DAG ID ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The endpoint to get list of dag_runs for a specific dag_id have changed from +The endpoint to get the list of dag_runs for a specific dag_id has changed from .. http:get:: /api/experimental/dags//dag_runs @@ -56,8 +56,7 @@ 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. +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//dag_runs/ @@ -68,7 +67,7 @@ reference documentaion for more information Health endpoint ^^^^^^^^^^^^^^^ The operation previously performed in the experimental REST API endpoint to check -the health status have changed from +the health status has changed from .. http:get:: /api/experimental/test @@ -78,7 +77,7 @@ to Task information endpoint ^^^^^^^^^^^^^^^^^^^^^^^^^ -The endpoint for getting a task information have changed from +The endpoint for getting task information has changed from .. http:get:: /api/experimental/dags//tasks/ @@ -88,8 +87,8 @@ to Task Instance ^^^^^^^^^^^^^ -The endpoint for getting task instance`s public instance variable -have changed from +The endpoint for getting task instance's public instance variable +has changed from .. http:get:: /api/experimental/dags//dag_runs//tasks/ @@ -101,7 +100,7 @@ Please check the Stable API reference documentaion for more information DAG ^^^ -The endpoint for pausing a dag have changed from +The endpoint for pausing a dag has changed from .. http:get:: /api/experimental/dags//paused/ @@ -109,7 +108,7 @@ to .. http:patch:: /api/v1/dags/{dag_id} -while getting information about the paused state of a dag have changed from +while getting information about the paused state of a dag has changed from .. http:get:: /api/experimental/dags//paused @@ -134,9 +133,9 @@ 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 +Get all Pools ^^^^^^^^^^^^^ -The endpoint for getting all pools have changed from +The endpoint for getting all pools has changed from .. http:get:: /api/experimental/pools @@ -146,7 +145,7 @@ to Get pool by a given name ^^^^^^^^^^^^^^^^^^^^^^^^ -The endpoint to get pool by a given name have changed from +The endpoint to get pool by a given name has changed from .. http:get:: /api/experimental/pools/ @@ -154,9 +153,9 @@ to .. http:get:: /api/v1/pools/{pool_name} -Create a pool +Create a Pool ^^^^^^^^^^^^^ -The endpoint for creating a pool have changed from +The endpoint for creating a pool has changed from .. http:post:: /api/experimental/pools @@ -164,9 +163,9 @@ to .. http:post:: /api/v1/pools -Delete a pool +Delete a Pool ^^^^^^^^^^^^^ -The endpoint for deleting a pool have changed from +The endpoint for deleting a pool has changed from .. http:delete:: /api/experimental/pools/ @@ -174,7 +173,7 @@ to .. http:delete:: /api/v1/pools/{pool_name} -Lineage of a DAG +DAG Lineage ^^^^^^^^^^^^^^^^ The endpoint for returning the lineage of a dag have changed from From a95be88331eb004567513bae9c108709f767d6aa Mon Sep 17 00:00:00 2001 From: Ephraim Anierobi Date: Sun, 12 Jul 2020 00:45:40 +0100 Subject: [PATCH 4/5] Update docs/stable-rest-api/migration.rst --- docs/stable-rest-api/migration.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/stable-rest-api/migration.rst b/docs/stable-rest-api/migration.rst index 9d609b7a5784b..5f0cfd3e0e5fe 100644 --- a/docs/stable-rest-api/migration.rst +++ b/docs/stable-rest-api/migration.rst @@ -174,7 +174,7 @@ 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/// From cc089e401df9412c769a2e19fa5879617495f95a Mon Sep 17 00:00:00 2001 From: Ephraim Anierobi Date: Mon, 13 Jul 2020 23:47:33 +0100 Subject: [PATCH 5/5] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Kamil BreguĊ‚a --- docs/stable-rest-api/migration.rst | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/docs/stable-rest-api/migration.rst b/docs/stable-rest-api/migration.rst index 5f0cfd3e0e5fe..cd690d58c6ef5 100644 --- a/docs/stable-rest-api/migration.rst +++ b/docs/stable-rest-api/migration.rst @@ -27,7 +27,7 @@ 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 in migrating from the +differences between the two endpoints that will help you migrate from the experimental REST API to the stable REST API. Base Endpoint @@ -61,8 +61,7 @@ Therefore the operation previously performed by this endpoint .. http:get:: /api/experimental/dags//dag_runs/ -can now be handled with filter parameters in the query string. Please check the -reference documentaion for more information +can now be handled with filter parameters in the query string. Health endpoint ^^^^^^^^^^^^^^^ @@ -96,7 +95,6 @@ to .. http:get:: /api/v1/dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances/{task_id} -Please check the Stable API reference documentaion for more information DAG ^^^ @@ -116,7 +114,6 @@ to .. http:get:: /api/v1/dags/{dag_id} -Please check the Stable API reference documentaion for more information Latest DAG Runs ^^^^^^^^^^^^^^^ @@ -182,6 +179,3 @@ The endpoint for returning the lineage of a dag have changed from to .. http:get:: /api/v1/dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances/{task_id}/xcomEntries - -More information about using this endpoint can be found in the stable REST API -documentation