mik-laj commented on a change in pull request #8721: URL: https://github.com/apache/airflow/pull/8721#discussion_r431877857
########## File path: openapi.yaml ########## @@ -0,0 +1,2411 @@ +# 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. +--- +openapi: 3.0.3 + +info: + title: "Airflow API (Stable)" + description: Apache Airflow management API. + version: '1.0.0' + license: + name: Apache 2.0 + url: http://www.apache.org/licenses/LICENSE-2.0.html + contact: + name: Apache Foundation + url: https://airflow.apache.org + email: d...@airflow.apache.org + +servers: + - url: /api/v1 + description: Airfow Stable API. + +paths: + # Database entities + /connections: + get: + summary: Get all connection entries + operationId: getConnections + tags: [Connection] + parameters: + - $ref: '#/components/parameters/PageLimit' + - $ref: '#/components/parameters/PageOffset' + responses: + '200': + description: List of connection entry. + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/ConnectionCollection' + - $ref: '#/components/schemas/CollectionInfo' + '401': + $ref: '#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/PermissionDenied' + + post: + summary: Create connection entry + operationId: createConnection + tags: [Connection] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/Connection' + responses: + '200': + description: Successful response. + content: + application/json: + schema: + $ref: '#/components/schemas/Connection' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/PermissionDenied' + + /connections/{connection_id}: + parameters: + - $ref: '#/components/parameters/ConnectionID' + + get: + summary: Get a connection entry + operationId: getConnection + tags: [Connection] + responses: + '200': + description: Successful response. + content: + application/json: + schema: + $ref: '#/components/schemas/Connection' + '401': + $ref: '#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/PermissionDenied' + '404': + $ref: '#/components/responses/NotFound' + + patch: + summary: Update a connection entry + operationId: updaateConnection + tags: [Connection] + parameters: + - $ref: '#/components/parameters/UpdateMask' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/Connection' + + responses: + '200': + description: Successful response. + content: + application/json: + schema: + $ref: '#/components/schemas/Connection' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/PermissionDenied' + '404': + $ref: '#/components/responses/NotFound' + + delete: + summary: Delete a connection entry + operationId: deleteConnection + tags: [Connection] + responses: + '204': + description: No content. + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/PermissionDenied' + + /dags: + get: + summary: Get all DAGs + operationId: getDags + tags: [DAG] + parameters: + - $ref: '#/components/parameters/PageLimit' + - $ref: '#/components/parameters/PageOffset' + responses: + '200': + description: List of DAGs. + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/DAGCollection' + - $ref: '#/components/schemas/CollectionInfo' + '401': + $ref: '#/components/responses/Unauthenticated' + + /dags/{dag_id}: + parameters: + - $ref: '#/components/parameters/DAGID' + + get: + summary: Get basic information about a DAG + description: Presents only information available in database (DAGModel). + operationId: getDag + tags: [DAG] + responses: + '200': + description: Successful response. + content: + application/json: + schema: + $ref: '#/components/schemas/DAG' + '401': + $ref: '#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/PermissionDenied' + '404': + $ref: '#/components/responses/NotFound' + + patch: + summary: Update a DAG + operationId: updateDag + tags: [DAG] + responses: + '200': + description: Successful response. + content: + application/json: + schema: + $ref: '#/components/schemas/DAG' + '401': + $ref: '#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/PermissionDenied' + '404': + $ref: '#/components/responses/NotFound' + + /dags/{dag_id}/clearTaskInstanaces: + parameters: + - $ref: '#/components/parameters/DAGID' + + post: + summary: Clears a set of task instances associated with the DAAG for a specified date range. + operationId: clearTaskInstaance + tags: [DAG] + requestBody: + description: Parameters of action + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ClearTaskInstance' + + responses: + '200': + description: A list of cleared tasks + content: + application/json: + schema: + $ref: '#/components/schemas/TaskInstanceCollection' + '401': + $ref: '#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/PermissionDenied' + '404': + $ref: '#/components/responses/NotFound' + + /dags/{dag_id}/dagRuns: + parameters: + - $ref: '#/components/parameters/DAGID' + + get: + summary: Get all DAG Runs + description: > + This endpoint support reading resources across multiple DAGs by specifying a "~" as a dag_id. + operationId: getDagRuns + tags: [DAGRun] + parameters: + - $ref: '#/components/parameters/PageLimit' + - $ref: '#/components/parameters/PageOffset' + - $ref: '#/components/parameters/FilterExecutionDateGTE' + - $ref: '#/components/parameters/FilterExecutionDateLTE' + - $ref: '#/components/parameters/FilterStartDateGTE' + - $ref: '#/components/parameters/FilterStartDateLTE' + - $ref: '#/components/parameters/FilterEndDateGTE' + - $ref: '#/components/parameters/FilterEndDateLTE' + responses: + '200': + description: List of DAG Runs. + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/DAGRunCollection' + - $ref: '#/components/schemas/CollectionInfo' + '401': + $ref: '#/components/responses/Unauthenticated' + + /dags/~/dagRuns/list: + post: + summary: Get all DAG Runs. + description: > + It allows you to fetch DAG Runs from many DAGs. + operationId: getDagRunsBatch + tags: [DAGRun] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ListDagRunsForm' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/ListDagRunsForm' + responses: + '200': + description: List of DAG Runs. + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/DAGRunCollection' + - $ref: '#/components/schemas/CollectionInfo' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/PermissionDenied' + + /dags/{dag_id}/dagRuns/{execution_date}: + parameters: + - $ref: '#/components/parameters/DAGID' + - $ref: '#/components/parameters/ExecutionDate' + + get: + summary: Get a DAG Run + operationId: getDagRun + tags: [DAGRun] + responses: + '200': + description: Successful response. + content: + application/json: + schema: + $ref: '#/components/schemas/DAGRun' + '401': + $ref: '#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/PermissionDenied' + '404': + $ref: '#/components/responses/NotFound' + + post: + summary: Trigger a DAG Run + operationId: createDagRun + tags: [DAGRun] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/DAGRun' Review comment: I'm afraid that it can still cause various problems. When I write about strongly typed language, I mean Java/C++. In Java, there are two different libraries that are written with a completely different philosophy. * Unstructured JSON e.g. Json-Simple API - This creates special JSON objects that are used to store data. Thanks to this you can process any objects, but the API is not very pleasant and you don't have type hints. This is similar to the approach available in Python. ``` import java.io.FileReader; import java.util.Iterator; import java.util.Map; import org.json.simple.JSONArray; import org.json.simple.JSONObject; import org.json.simple.parser.*; public class JSONReadExample { public static void main(String[] args) throws Exception { // parsing file "JSONExample.json" Object obj = new JSONParser().parse(new FileReader("JSONExample.json")); // typecasting obj to JSONObject JSONObject jo = (JSONObject) obj; // getting firstName and lastName String firstName = (String) jo.get("firstName"); String lastName = (String) jo.get("lastName"); System.out.println(firstName); System.out.println(lastName); // getting age long age = (long) jo.get("age"); System.out.println(age); // getting address Map address = ((Map)jo.get("address")); // iterating address Map Iterator<Map.Entry> itr1 = address.entrySet().iterator(); while (itr1.hasNext()) { Map.Entry pair = itr1.next(); System.out.println(pair.getKey() + " : " + pair.getValue()); } // getting phoneNumbers JSONArray ja = (JSONArray) jo.get("phoneNumbers"); // iterating phoneNumbers Iterator itr2 = ja.iterator(); while (itr2.hasNext()) { itr1 = ((Map) itr2.next()).entrySet().iterator(); while (itr1.hasNext()) { Map.Entry pair = itr1.next(); System.out.println(pair.getKey() + " : " + pair.getValue()); } } } } ``` * Structured JSON e.g. GSON - An approach that requires you to define classes for all objects before using them. This means that you must convert OpneAPI schemas to the corresponding class languages before use. ``` public class Car { public String brand = null; public int doors = 0; } String json = "{\"brand\":\"Jeep\", \"doors\": 3}"; Gson gson = new Gson(); Car car = gson.fromJson(json, Car.class); ``` This approach is very popular in the Java world because it provides type hints and is closest to the philosophy of the language. In our API it is necessary to use both approaches because for conf field we are not able to specify a specific type. The easiest way to do this is to use two different libraries. Of course, there are workarounds that can also process unstructured JSON in a GSON also, but we cannot guarantee that such a workaround will exist in every language and library. The processing of structured JSON objects and unstructured JSON objects are completely two different problems, and most often completely different libraries are used. ---------------------------------------------------------------- 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: us...@infra.apache.org
