From 11246851978360e5b29ee84b02dfdf88fbedca59 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Sun, 10 Nov 2024 11:15:26 -0800 Subject: [PATCH 1/3] initial draft TAP-1.1 OpenAPI spec --- openapi/openapi.yaml | 35 +++++++++++++++++ openapi/parameters/dali-maxrec.yaml | 6 +++ openapi/parameters/dali-responseformat.yaml | 5 +++ openapi/parameters/tap-format.yaml | 5 +++ openapi/parameters/tap-lang.yaml | 6 +++ openapi/parameters/tap-params.yaml | 39 +++++++++++++++++++ openapi/parameters/tap-query.yaml | 6 +++ openapi/parameters/tap-upload.yaml | 5 +++ openapi/tap-async.yaml | 28 ++++++++++++++ openapi/tap-load.yaml | 39 +++++++++++++++++++ openapi/tap-responses.yaml | 7 ++++ openapi/tap-sync.yaml | 43 +++++++++++++++++++++ 12 files changed, 224 insertions(+) create mode 100644 openapi/openapi.yaml create mode 100644 openapi/parameters/dali-maxrec.yaml create mode 100644 openapi/parameters/dali-responseformat.yaml create mode 100644 openapi/parameters/tap-format.yaml create mode 100644 openapi/parameters/tap-lang.yaml create mode 100644 openapi/parameters/tap-params.yaml create mode 100644 openapi/parameters/tap-query.yaml create mode 100644 openapi/parameters/tap-upload.yaml create mode 100644 openapi/tap-async.yaml create mode 100644 openapi/tap-load.yaml create mode 100644 openapi/tap-responses.yaml create mode 100644 openapi/tap-sync.yaml diff --git a/openapi/openapi.yaml b/openapi/openapi.yaml new file mode 100644 index 0000000..9342b7b --- /dev/null +++ b/openapi/openapi.yaml @@ -0,0 +1,35 @@ +openapi: 3.1.0 +info: + title: TAP service endpoints + version: "1.1" + description: This is more or less the current TAP-1.1 standard. +servers: +- url: /example +paths: +# notes: the tap openapi components are included here; +# the uws- and vosi- components are not included here and would have to +# use the $ref: {URL} style or be pulled in when building the complete +# stand-alone spec/document structure (TBD) + /sync: + $ref: ./tap-sync.yaml + + /async: + $ref: ./tap-async.yaml + /async/{jobID}: + $ref: ./include/UWS/uws-job.yaml + #$ref: https://ivoa.net/std/UWS/uws-job.yaml + ## TODO: more resources under /async/{jobID} here... + + /tables: + $ref: ./include/VOSI/vosi-tableset.yaml + #$ref: https://ivoa.net/std/VOSI/vosi-tableset.yaml + /tables/{name}: + $ref: ./include/VOSI/vosi-table.yaml + #$ref: https://ivoa.net/std/VOSI/vosi-table.yaml + + /availability: + $ref: ./include/VOSI/vosi-availability.yaml + #$ref: https://ivoa.net/std/VOSI/vosi-availability.yaml + /capabilities: + $ref: ./include/VOSI/vosi-capabilities.yaml + #$ref: https://ivoa.net/std/VOSI/vosi-capabilities.yaml diff --git a/openapi/parameters/dali-maxrec.yaml b/openapi/parameters/dali-maxrec.yaml new file mode 100644 index 0000000..9260433 --- /dev/null +++ b/openapi/parameters/dali-maxrec.yaml @@ -0,0 +1,6 @@ +name: MAXREC +in: query +description: request a specific limit on number of rows to return +schema: + type: integer + format: int64 diff --git a/openapi/parameters/dali-responseformat.yaml b/openapi/parameters/dali-responseformat.yaml new file mode 100644 index 0000000..202eee4 --- /dev/null +++ b/openapi/parameters/dali-responseformat.yaml @@ -0,0 +1,5 @@ +name: RESPONSEFORMAT +in: query +description: select output table format +schema: + type: string diff --git a/openapi/parameters/tap-format.yaml b/openapi/parameters/tap-format.yaml new file mode 100644 index 0000000..40c253b --- /dev/null +++ b/openapi/parameters/tap-format.yaml @@ -0,0 +1,5 @@ +name: FORMAT +in: query +description: "supported for backwards compatibility to 1.0 (see: RESPONSEFORMAT)" +schema: + type: string diff --git a/openapi/parameters/tap-lang.yaml b/openapi/parameters/tap-lang.yaml new file mode 100644 index 0000000..c432ae7 --- /dev/null +++ b/openapi/parameters/tap-lang.yaml @@ -0,0 +1,6 @@ +name: LANG +in: query +description: specify the query language used in the QUERY parameter +required: true +schema: + type: string diff --git a/openapi/parameters/tap-params.yaml b/openapi/parameters/tap-params.yaml new file mode 100644 index 0000000..6ab3791 --- /dev/null +++ b/openapi/parameters/tap-params.yaml @@ -0,0 +1,39 @@ + LANG: + name: LANG + in: query + description: specify the query language used in the QUERY parameter + required: true + schema: + type: string + QUERY: + name: QUERY + in: query + description: specify the query + required: true + schema: + type: string + FORMAT: + name: FORMAT + in: query + description: "supported for backwards compatibility to 1.0 (see: RESPONSEFORMAT)" + schema: + type: string + RESPONSEFORMAT: + name: RESPONSEFORMAT + in: query + description: select output table format + schema: + type: string + MAXREC: + name: MAXREC + in: query + description: request a specific limit on number of rows to return + schema: + type: integer + format: int64 + UPLOAD: + name: UPLOAD + in: query + description: specify name,location pair for a table to be uploaded and used in the query + schema: + type: string diff --git a/openapi/parameters/tap-query.yaml b/openapi/parameters/tap-query.yaml new file mode 100644 index 0000000..92e9c20 --- /dev/null +++ b/openapi/parameters/tap-query.yaml @@ -0,0 +1,6 @@ +name: QUERY +in: query +description: specify the query +required: true +schema: + type: string diff --git a/openapi/parameters/tap-upload.yaml b/openapi/parameters/tap-upload.yaml new file mode 100644 index 0000000..27302d6 --- /dev/null +++ b/openapi/parameters/tap-upload.yaml @@ -0,0 +1,5 @@ +name: UPLOAD +in: query +description: specify name,location pair for a table to be uploaded and used in the query +schema: + type: string diff --git a/openapi/tap-async.yaml b/openapi/tap-async.yaml new file mode 100644 index 0000000..473631d --- /dev/null +++ b/openapi/tap-async.yaml @@ -0,0 +1,28 @@ +get: + summary: UWS 1.1 + description: async job listing + parameters: + responses: + 200: + $ref: ./include/UWS/uws-responses.yaml#/job-listing + 401: + $ref: ./include/VOSI/std-responses.yaml#/not-authenticated + 403: + $ref: ./include/VOSI/std-responses.yaml#/permission-denied +post: + summary: TAP-async 1.1 + description: TAP asynchronous query endpoint (create UWS Job) + parameters: + - $ref: ./parameters/tap-lang.yaml + - $ref: ./parameters/tap-query.yaml + - $ref: ./parameters/tap-upload.yaml + - $ref: ./parameters/tap-format.yaml + - $ref: ./parameters/dali-maxrec.yaml + - $ref: ./parameters/dali-responseformat.yaml + responses: + 303: + $ref: ./include/UWS/uws-responses.yaml#/created + 401: + $ref: ./include/VOSI/std-responses.yaml#/not-authenticated + 403: + $ref: ./include/VOSI/std-responses.yaml#/permission-denied diff --git a/openapi/tap-load.yaml b/openapi/tap-load.yaml new file mode 100644 index 0000000..710fa86 --- /dev/null +++ b/openapi/tap-load.yaml @@ -0,0 +1,39 @@ +post: + summary: bulk load or row data + description: TAP synchronous bulk load endpoint + parameters: + - name: name + in: path + description: a single table name as provided in tap_schema + required: true + schema: + type: string + requestBody: + required: true + $ref: '#/components/schemas/tableRows' + + responses: + "200": + description: | + rows loaded; + TBD: both partial or complete are possible + +components: + schemas: + tableRows: + content: + text/tab-separated-values: + schema: + type: string + text/csv: + schema: + type: string + application/fits: + application/x-votable+xml: + schema: + type: object + xml: + name: VOTABLE + namespace: http://www.ivoa.net/xml/VOTable/v1.3 + + \ No newline at end of file diff --git a/openapi/tap-responses.yaml b/openapi/tap-responses.yaml new file mode 100644 index 0000000..cc11415 --- /dev/null +++ b/openapi/tap-responses.yaml @@ -0,0 +1,7 @@ +# UWS create job response +invalid-query: + description: the requested TAP query job is invalid; this is usually the ADQL query + content: + text/plain: + schema: + type: string diff --git a/openapi/tap-sync.yaml b/openapi/tap-sync.yaml new file mode 100644 index 0000000..037382b --- /dev/null +++ b/openapi/tap-sync.yaml @@ -0,0 +1,43 @@ +get: + summary: TAP-sync 1.1 + description: TAP synchronous query endpoint + parameters: + - $ref: ./parameters/tap-lang.yaml + - $ref: ./parameters/tap-query.yaml + - $ref: ./parameters/tap-upload.yaml + - $ref: ./parameters/tap-format.yaml + - $ref: ./parameters/dali-maxrec.yaml + - $ref: ./parameters/dali-responseformat.yaml + responses: + 200: + description: successful response + 303: + description: redirect to the job result (optional) + 400: + $ref: ./tap-responses.yaml#/invalid-query + 401: + $ref: ./include/VOSI/std-responses.yaml#/not-authenticated + 403: + $ref: ./include/VOSI/std-responses.yaml#/permission-denied +post: + summary: TAP-sync 1.1 + description: TAP synchronous query endpoint + parameters: + - $ref: ./parameters/tap-lang.yaml + - $ref: ./parameters/tap-query.yaml + - $ref: ./parameters/tap-upload.yaml + - $ref: ./parameters/tap-format.yaml + - $ref: ./parameters/dali-maxrec.yaml + - $ref: ./parameters/dali-responseformat.yaml + responses: + 200: + description: successful response + 303: + description: redirect to the job result (optional) + 400: + $ref: ./tap-responses.yaml#/invalid-query + 401: + $ref: ./include/VOSI/std-responses.yaml#/not-authenticated + 403: + $ref: ./include/VOSI/std-responses.yaml#/permission-denied + From 043fe3790436cf9a60aa854ab7eaea87a7c9d895 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Sun, 10 Nov 2024 11:21:26 -0800 Subject: [PATCH 2/3] remove cruft --- openapi/parameters/tap-params.yaml | 39 ------------------------------ 1 file changed, 39 deletions(-) delete mode 100644 openapi/parameters/tap-params.yaml diff --git a/openapi/parameters/tap-params.yaml b/openapi/parameters/tap-params.yaml deleted file mode 100644 index 6ab3791..0000000 --- a/openapi/parameters/tap-params.yaml +++ /dev/null @@ -1,39 +0,0 @@ - LANG: - name: LANG - in: query - description: specify the query language used in the QUERY parameter - required: true - schema: - type: string - QUERY: - name: QUERY - in: query - description: specify the query - required: true - schema: - type: string - FORMAT: - name: FORMAT - in: query - description: "supported for backwards compatibility to 1.0 (see: RESPONSEFORMAT)" - schema: - type: string - RESPONSEFORMAT: - name: RESPONSEFORMAT - in: query - description: select output table format - schema: - type: string - MAXREC: - name: MAXREC - in: query - description: request a specific limit on number of rows to return - schema: - type: integer - format: int64 - UPLOAD: - name: UPLOAD - in: query - description: specify name,location pair for a table to be uploaded and used in the query - schema: - type: string From 2999b2872bcbad4d691e5d7a61752b238c6f6a09 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Sun, 10 Nov 2024 11:22:46 -0800 Subject: [PATCH 3/3] remove youcat bulk load spec --- openapi/tap-load.yaml | 39 --------------------------------------- 1 file changed, 39 deletions(-) delete mode 100644 openapi/tap-load.yaml diff --git a/openapi/tap-load.yaml b/openapi/tap-load.yaml deleted file mode 100644 index 710fa86..0000000 --- a/openapi/tap-load.yaml +++ /dev/null @@ -1,39 +0,0 @@ -post: - summary: bulk load or row data - description: TAP synchronous bulk load endpoint - parameters: - - name: name - in: path - description: a single table name as provided in tap_schema - required: true - schema: - type: string - requestBody: - required: true - $ref: '#/components/schemas/tableRows' - - responses: - "200": - description: | - rows loaded; - TBD: both partial or complete are possible - -components: - schemas: - tableRows: - content: - text/tab-separated-values: - schema: - type: string - text/csv: - schema: - type: string - application/fits: - application/x-votable+xml: - schema: - type: object - xml: - name: VOTABLE - namespace: http://www.ivoa.net/xml/VOTable/v1.3 - - \ No newline at end of file