From d1d37c1f16164ba0d423c2caca9f1f65094889c9 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Mon, 15 Jul 2024 14:59:45 -0700 Subject: [PATCH 01/23] youcat: initial openapi based api docs --- youcat/build.gradle | 4 +- youcat/src/main/webapp/index.html | 188 ++------ youcat/src/main/webapp/openapi.yaml | 636 ++++++++++++++++++++++++++++ 3 files changed, 667 insertions(+), 161 deletions(-) create mode 100644 youcat/src/main/webapp/openapi.yaml diff --git a/youcat/build.gradle b/youcat/build.gradle index f5ca5a5f..5ddaaf6b 100644 --- a/youcat/build.gradle +++ b/youcat/build.gradle @@ -17,9 +17,9 @@ sourceCompatibility = 11 group = 'ca.nrc.cadc' war { - // Include the swagger-ui so that /cat provides the cat API documentation + // Include the swagger UI so that base URL provides API docs from(System.getenv('RPS') + '/resources/') { - include 'swagger-ui/' + include 'swagger-openapi/dist/' } } diff --git a/youcat/src/main/webapp/index.html b/youcat/src/main/webapp/index.html index 67b991f8..37094d97 100644 --- a/youcat/src/main/webapp/index.html +++ b/youcat/src/main/webapp/index.html @@ -1,165 +1,35 @@ - + - - youcat API - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + youcat API - - - -
 
-
+ +
+ + + + diff --git a/youcat/src/main/webapp/openapi.yaml b/youcat/src/main/webapp/openapi.yaml new file mode 100644 index 00000000..0001cd7f --- /dev/null +++ b/youcat/src/main/webapp/openapi.yaml @@ -0,0 +1,636 @@ +openapi: 3.0.1 +info: + title: user-managed TAP service (youcat) + description: "This page contains technical API information.\n\nThis service implements\ + \ the IVOA TAP-1.1\ + \ Recommendation plus extensions to support table creation and bulk loading of\ + \ content.\n\nThe endpoints listed below support both anonymous and authenticated\ + \ access (using client certificate or cookie).\n\n YouCat supports user management\ + \ of permissions at both the schema and table level. A schema owner is set when\ + \ a YouCat allocation is created by the service operator. Table owners are set\ + \ to be the user who created the table. Owners can set a flag for anonymous reading\ + \ and can set groups for read-only and read-write permissons.\n The following\ + \ describes how the permissions are enforced on schemas and tables:\n\n \t{schema|table}.public\ + \ = false|true\n \t\tallows querying via TAP API\n \t{schema|table|.read-only\ + \ = NULL | {group URI}\n \t\tread-only permission on a schema: allows TAP API\ + \ to expose table\n \t\tread-only permission on table: allows TAP API to expose\ + \ content of a table\n \t{schema|table}.read-write = NULL | {group URI}\n \t\t\ + read-write permissions on a schema: read-only + create table\n \t\tread-write\ + \ permission on a table: read-only + create index, append rows, update (tap_schema)\ + \ metadata\n \t{schema|table}.owner\n \t\towner of a schema has: read-write +\ + \ drop (any) table\n \t\towner of a table has: read-write + drop table\n \t\t\ + owner of a schema: change permissions on schema and all tables\n \t\towner of\ + \ a table: change permissions on table\n\nGroup URIs are in the format:\n\n \t\ + {resourceID?{groupName}\n\nwhere {resourceID} is a registered GMS service and \ + {groupName} is a group managed by that service (e.g. ivo://example.net/gms?my-group." + version: "1.0" +servers: +- url: /youcat +paths: + /async: + post: + tags: + - TAP + summary: IVOA TAP v1.1 + description: | + TAP asynchronous query endpoint (create UWS Job) + parameters: + - name: LANG + in: query + description: specify the query language used in the QUERY parameter + required: true + schema: + type: string + - name: QUERY + in: query + description: specify the query + required: true + schema: + type: string + - name: FORMAT + in: query + description: "supported for backwards compatibility to 1.0 (see: RESPONSEFORMAT)" + schema: + type: string + - name: RESPONSEFORMAT + in: query + description: select output table format + schema: + type: string + - name: MAXREC + in: query + description: request a specific limit on number of rows to return + schema: + type: integer + format: int64 + - name: DEST + in: query + description: specify destination where output should be written (VOSpace URI) + schema: + type: string + format: uri + - name: UPLOAD + in: query + description: "specify name,location pair for a table to be uploaded and used\ + \ in the query" + schema: + type: string + responses: + "200": + description: Successful response + content: {} + "303": + description: standard UWS redirect to the created job + content: {} + "401": + description: Unauthorized - User not authenticated + content: {} + "403": + description: Permission Denied - Table(s) not readable + content: {} + "404": + description: Not Found - Table(s) not found + content: {} + "500": + description: Internal error + content: {} + "503": + description: Service busy + content: {} + default: + description: Unexpeced error + content: + text/xml: + schema: + $ref: '#/components/schemas/Error' + /sync: + get: + tags: + - TAP + summary: IVOA TAP v1.1 + description: | + TAP synchronous query endpoint + parameters: + - name: LANG + in: query + description: specify the query language used in the QUERY parameter + required: true + schema: + type: string + - name: QUERY + in: query + description: specify the query + required: true + schema: + type: string + - name: FORMAT + in: query + description: "supported for backwards compatibility to 1.0 (see: RESPONSEFORMAT)" + schema: + type: string + - name: RESPONSEFORMAT + in: query + description: select output table format + schema: + type: string + - name: MAXREC + in: query + description: request a specific limit on number of rows to return + schema: + type: integer + format: int64 + - name: UPLOAD + in: query + description: "specify name,location pair for a table to be uploaded and used\ + \ in the query" + schema: + type: string + responses: + "200": + description: Successful response + content: {} + "401": + description: Unauthorized - User not authenticated + content: {} + "403": + description: Permission Denied - Table(s) not readable + content: {} + "404": + description: Not Found - Table(s) not found + content: {} + "500": + description: Internal error + content: {} + "503": + description: Service busy + content: {} + default: + description: Unexpeced error + content: + application/x-votable+/xml: + schema: + $ref: '#/components/schemas/Error' + post: + tags: + - TAP + summary: IVOA TAP v1.1 + description: | + TAP synchronous query endpoint + parameters: + - name: LANG + in: query + description: specify the query language used in the QUERY parameter + required: true + schema: + type: string + - name: QUERY + in: query + description: specify the query + required: true + schema: + type: string + - name: FORMAT + in: query + description: "supported for backwards compatibility to 1.0 (see: RESPONSEFORMAT)" + schema: + type: string + - name: RESPONSEFORMAT + in: query + description: select output table format + schema: + type: string + - name: MAXREC + in: query + description: request a specific limit on number of rows to return + schema: + type: integer + format: int64 + - name: UPLOAD + in: query + description: "specify name,location pair for a table to be uploaded and used\ + \ in the query" + schema: + type: string + responses: + "200": + description: Successful response + content: {} + "401": + description: Unauthorized - User not authenticated + content: {} + "403": + description: Permission denied - Table(s) not readable + content: {} + "404": + description: Not Found - Table(s) not found + content: {} + "500": + description: Internal error + content: {} + "503": + description: Service busy + content: {} + default: + description: Unexpeced error + content: + application/x-votable+/xml: + schema: + $ref: '#/components/schemas/Error' + /availability: + get: + tags: + - Support Interfaces + summary: VOSI Availability + description: "Indicates whether the service is operable and shows the reliability\ + \ of the service for extended and scheduled requests. If the query parameter\ + \ 'detail=min' is used, a light weight heart beat test will be performed.\ + \ The heart beat test returns status 200 if the service is available." + parameters: + - name: detail + in: query + description: "specifies heart beat to be used to check for availability of\ + \ this service, the value 'min' must be used, otherwise the full availability\ + \ test will be performed" + schema: + type: string + responses: + "200": + description: A VOSI availability document in XML. + content: + text/xml: + schema: + $ref: '#/components/schemas/availability' + default: + description: Unexpected error + content: + text/xml: + schema: + $ref: '#/components/schemas/Error' + /capabilities: + get: + tags: + - Support Interfaces + summary: VOSI Capabilities + description: "Provides the service metadata in the form of a list of Capability\ + \ descriptions. Each of these descriptions is an \nXML element that:\n\n" + responses: + "200": + description: A VOSI Capabilities document in XML. + content: + text/xml: + schema: + $ref: '#/components/schemas/capabilities' + "500": + description: Internal server error + content: {} + "503": + description: Service too busy + content: {} + default: + description: Unexpected error + content: + text/xml: + schema: + $ref: '#/components/schemas/Error' + /tables: + get: + tags: + - Support Interfaces + summary: VOSI Tables + description: | + Provides the table metadata in the form of a TableSet descriptions. + responses: + "200": + description: A VOSI document in XML. + content: + text/xml: + schema: + $ref: '#/components/schemas/tables' + "500": + description: Internal server error + content: {} + "503": + description: Service too busy + content: {} + default: + description: Unexpected error + content: + text/xml: + schema: + $ref: '#/components/schemas/Error' + /tables/{name}: + get: + tags: + - Support Interfaces + summary: get table metadata (VOSI) + description: | + Provides the table metadata for a single table. + parameters: + - name: name + in: path + description: a single fully qualified table name (e.g. tap_schema.tables) + required: true + schema: + type: string + responses: + "200": + description: A VOSI document in XML. + content: + text/xml: + schema: + $ref: '#/components/schemas/tables' + "500": + description: Internal server error + content: {} + "503": + description: Service too busy + content: {} + default: + description: Unexpected error + content: + text/xml: + schema: + $ref: '#/components/schemas/Error' + put: + tags: + - Custom Features + summary: create table + description: | + table description in VOSI table or VOTable (no rows) format + parameters: + - name: name + in: path + description: | + the fully qualified name of the table to create + required: true + schema: + type: string + responses: + "201": + description: table created + content: {} + "400": + description: create table failed due to invalid input + content: {} + "500": + description: Internal server error + content: {} + "503": + description: Service too busy + content: {} + default: + description: Unexpected error + content: + '*/*': + schema: + $ref: '#/components/schemas/Error' + delete: + tags: + - Custom Features + summary: drop table + parameters: + - name: name + in: path + description: the table to drop + required: true + schema: + type: string + responses: + "200": + description: table dropped + content: {} + "500": + description: Internal server error + content: {} + "503": + description: Service too busy + content: {} + default: + description: Unexpected error + content: + '*/*': + schema: + $ref: '#/components/schemas/Error' + /permissions/{name}: + get: + tags: + - Custom Features + summary: view schema or table permissions + description: | + View the owner, public flag, read group, and write group of a schema or table. + parameters: + - name: name + in: path + description: name of the schema or table to view. + required: true + schema: + type: string + responses: + "200": + description: successful request + content: {} + "400": + description: invalid syntax + content: {} + "500": + description: Internal server error + content: {} + "503": + description: Service too busy + content: {} + default: + description: Unexpected error + content: + '*/*': + schema: + $ref: '#/components/schemas/Error' + post: + tags: + - Custom Features + summary: modify schema or table permissions + description: | + Modify any of the public flag, readGroup or writeGroup of a schema or table. These operations are permitted by the owner of the schema and owners of the target tables. Parameters are in-line CFLF separated entries in key=value format. An example of a groupURI is ivo://cadc.nrc.ca/gms?myGroup + parameters: + - name: name + in: path + description: name of the schema or table to modify. + required: true + schema: + type: string + requestBody: + description: set or clear read/write group. rw-group=groupURI or rw-group= + to clear. group URI in format ivo://cadc.nrc.ca/gms?groupName + content: + text/plain: {} + required: false + responses: + "200": + description: permissions updated successfully + content: {} + "400": + description: invalid permission syntax + content: {} + "403": + description: Insufficient permission to change permissions + content: {} + "500": + description: Internal server error + content: {} + "503": + description: Service too busy + content: {} + default: + description: Unexpected error + content: + '*/*': + schema: + $ref: '#/components/schemas/Error' + x-codegen-request-body-name: rw-group + /load/{tableName}: + post: + tags: + - Custom Features + summary: sync streaming row insert + description: | + Bulk load rows and append to the table. This currently supports input data in CSV and TSV format (with header), and FITS Binary Tables + parameters: + - name: tableName + in: path + description: a single fully qualified table name (e.g. tap_schema.tables) + required: true + schema: + type: string + responses: + "200": + description: rows successfully inserted + content: + '*/*': + schema: + $ref: '#/components/schemas/tables' + "400": + description: insert rows failed due to invalid input + content: {} + "500": + description: Internal server error + content: {} + "503": + description: Service too busy + content: {} + default: + description: Unexpected error + content: + '*/*': + schema: + $ref: '#/components/schemas/Error' + /table-update: + post: + tags: + - Custom Features + summary: async table update (create UWS Job) + description: Asynchronous table update currently update supports index creation. + In future it will also support loading content (rows) from a remote location + (URI) + parameters: + - name: TABLE + in: query + description: "the table to update (TABLE={table name}): fully-qualified name\ + \ of the table to update" + required: true + schema: + type: string + - name: INDEX + in: query + description: "index a column (INDEX={column name}): value is the name of the\ + \ column to index; currently limited to single column only" + required: true + schema: + type: string + - name: UNIQUE + in: query + description: "create unique index (UNIQUE=true): use with INDEX={column name}\ + \ to make a unique index (default: false)" + schema: + type: boolean + responses: + "200": + description: Successful response + content: {} + "303": + description: standard UWS redirect to the created job + content: {} + "401": + description: Unauthorized - User not authenticated + content: {} + "404": + description: Not Found - User not found + content: {} + "500": + description: Internal error + content: {} + "503": + description: Service busy + content: {} + default: + description: Unexpeced error + content: + text/xml: + schema: + $ref: '#/components/schemas/Error' +components: + schemas: + Job: + type: string + availability: + type: object + properties: + available: + type: boolean + xml: + prefix: vosi + attribute: true + note: + type: string + xml: + prefix: vosi + attribute: true + xml: + name: availability + namespace: http://www.ivoa.net/xml/VOSIAvailability/v1.0 + prefix: vosi + tables: + type: object + properties: + available: + type: boolean + xml: + prefix: vosi + attribute: true + note: + type: string + xml: + prefix: vosi + attribute: true + xml: + namespace: http://www.ivoa.net/xml/VOSITables/v1.0 + prefix: vosi + capabilities: + type: object + xml: + namespace: http://www.ivoa.net/xml/VOSICapabilities/v1.0 + prefix: vosi + Error: + required: + - code + - message + type: object + properties: + code: + type: integer + format: int32 + message: + type: string + From d9a9d2703debea445741caa06ad4234bf873bca8 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Thu, 5 Sep 2024 14:56:27 -0700 Subject: [PATCH 02/23] progress on decomposing TAP openapi into importable fragments separate UWS and VOSI fragments and ref by URL --- .../components/parameters/dali-maxrec.yaml | 6 + .../parameters/dali-responseformat.yaml | 5 + .../components/parameters/tap-format.yaml | 5 + .../components/parameters/tap-lang.yaml | 6 + .../components/parameters/tap-params.yaml | 39 + .../components/parameters/tap-query.yaml | 6 + .../components/parameters/tap-upload.yaml | 5 + youcat/src/main/webapp/openapi.yaml | 681 ++------------- youcat/src/main/webapp/paths/tap-async.yaml | 37 + youcat/src/main/webapp/paths/tap-load.yaml | 45 + youcat/src/main/webapp/paths/tap-sync.yaml | 66 ++ .../main/webapp/paths/tap-table-update.yaml | 49 ++ .../src/main/webapp/paths/uws-job-phase.yaml | 58 ++ youcat/src/main/webapp/paths/uws-job.yaml | 31 + .../main/webapp/paths/vosi-availability.yaml | 31 + .../main/webapp/paths/vosi-capabilities.yaml | 27 + youcat/src/main/webapp/paths/vosi-table.yaml | 85 ++ .../src/main/webapp/paths/vosi-tableset.yaml | 32 + youcat/src/main/webapp/service.json | 772 ------------------ 19 files changed, 593 insertions(+), 1393 deletions(-) create mode 100644 youcat/src/main/webapp/components/parameters/dali-maxrec.yaml create mode 100644 youcat/src/main/webapp/components/parameters/dali-responseformat.yaml create mode 100644 youcat/src/main/webapp/components/parameters/tap-format.yaml create mode 100644 youcat/src/main/webapp/components/parameters/tap-lang.yaml create mode 100644 youcat/src/main/webapp/components/parameters/tap-params.yaml create mode 100644 youcat/src/main/webapp/components/parameters/tap-query.yaml create mode 100644 youcat/src/main/webapp/components/parameters/tap-upload.yaml create mode 100644 youcat/src/main/webapp/paths/tap-async.yaml create mode 100644 youcat/src/main/webapp/paths/tap-load.yaml create mode 100644 youcat/src/main/webapp/paths/tap-sync.yaml create mode 100644 youcat/src/main/webapp/paths/tap-table-update.yaml create mode 100644 youcat/src/main/webapp/paths/uws-job-phase.yaml create mode 100644 youcat/src/main/webapp/paths/uws-job.yaml create mode 100644 youcat/src/main/webapp/paths/vosi-availability.yaml create mode 100644 youcat/src/main/webapp/paths/vosi-capabilities.yaml create mode 100644 youcat/src/main/webapp/paths/vosi-table.yaml create mode 100644 youcat/src/main/webapp/paths/vosi-tableset.yaml delete mode 100644 youcat/src/main/webapp/service.json diff --git a/youcat/src/main/webapp/components/parameters/dali-maxrec.yaml b/youcat/src/main/webapp/components/parameters/dali-maxrec.yaml new file mode 100644 index 00000000..9260433f --- /dev/null +++ b/youcat/src/main/webapp/components/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/youcat/src/main/webapp/components/parameters/dali-responseformat.yaml b/youcat/src/main/webapp/components/parameters/dali-responseformat.yaml new file mode 100644 index 00000000..202eee4c --- /dev/null +++ b/youcat/src/main/webapp/components/parameters/dali-responseformat.yaml @@ -0,0 +1,5 @@ +name: RESPONSEFORMAT +in: query +description: select output table format +schema: + type: string diff --git a/youcat/src/main/webapp/components/parameters/tap-format.yaml b/youcat/src/main/webapp/components/parameters/tap-format.yaml new file mode 100644 index 00000000..40c253bf --- /dev/null +++ b/youcat/src/main/webapp/components/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/youcat/src/main/webapp/components/parameters/tap-lang.yaml b/youcat/src/main/webapp/components/parameters/tap-lang.yaml new file mode 100644 index 00000000..c432ae71 --- /dev/null +++ b/youcat/src/main/webapp/components/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/youcat/src/main/webapp/components/parameters/tap-params.yaml b/youcat/src/main/webapp/components/parameters/tap-params.yaml new file mode 100644 index 00000000..6ab3791c --- /dev/null +++ b/youcat/src/main/webapp/components/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/youcat/src/main/webapp/components/parameters/tap-query.yaml b/youcat/src/main/webapp/components/parameters/tap-query.yaml new file mode 100644 index 00000000..92e9c204 --- /dev/null +++ b/youcat/src/main/webapp/components/parameters/tap-query.yaml @@ -0,0 +1,6 @@ +name: QUERY +in: query +description: specify the query +required: true +schema: + type: string diff --git a/youcat/src/main/webapp/components/parameters/tap-upload.yaml b/youcat/src/main/webapp/components/parameters/tap-upload.yaml new file mode 100644 index 00000000..27302d60 --- /dev/null +++ b/youcat/src/main/webapp/components/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/youcat/src/main/webapp/openapi.yaml b/youcat/src/main/webapp/openapi.yaml index 0001cd7f..6dc56ea9 100644 --- a/youcat/src/main/webapp/openapi.yaml +++ b/youcat/src/main/webapp/openapi.yaml @@ -1,6 +1,7 @@ -openapi: 3.0.1 +openapi: 3.1.0 info: title: user-managed TAP service (youcat) + version: "1.0" description: "This page contains technical API information.\n\nThis service implements\ \ the IVOA TAP-1.1\ \ Recommendation plus extensions to support table creation and bulk loading of\ @@ -10,627 +11,65 @@ info: \ a YouCat allocation is created by the service operator. Table owners are set\ \ to be the user who created the table. Owners can set a flag for anonymous reading\ \ and can set groups for read-only and read-write permissons.\n The following\ - \ describes how the permissions are enforced on schemas and tables:\n\n \t{schema|table}.public\ - \ = false|true\n \t\tallows querying via TAP API\n \t{schema|table|.read-only\ - \ = NULL | {group URI}\n \t\tread-only permission on a schema: allows TAP API\ - \ to expose table\n \t\tread-only permission on table: allows TAP API to expose\ - \ content of a table\n \t{schema|table}.read-write = NULL | {group URI}\n \t\t\ - read-write permissions on a schema: read-only + create table\n \t\tread-write\ - \ permission on a table: read-only + create index, append rows, update (tap_schema)\ - \ metadata\n \t{schema|table}.owner\n \t\towner of a schema has: read-write +\ - \ drop (any) table\n \t\towner of a table has: read-write + drop table\n \t\t\ - owner of a schema: change permissions on schema and all tables\n \t\towner of\ - \ a table: change permissions on table\n\nGroup URIs are in the format:\n\n \t\ - {resourceID?{groupName}\n\nwhere {resourceID} is a registered GMS service and \ - {groupName} is a group managed by that service (e.g. ivo://example.net/gms?my-group." - version: "1.0" + \ describes how the permissions are enforced on schemas and tables:\ + \ \n\ + \ \n \t{schema|table}.public = false|true\ + \ \n \t\t allows querying via TAP API\ + \ \n \t{schema|table|.read-only = NULL | {group URI}\ + \ \n \t\t read-only permission on a schema: allows TAP API to expose table\ + \ \n \t\t read-only permission on table: allows TAP API to expose the content of a table\ + \ \n \t{schema|table}.read-write = NULL | {group URI}\ + \ \n \t\t read-write permissions on a schema: read-only + create table\ + \ \n \t\t read-write permission on a table: read-only + create index, append rows, update (tap_schema)\ + \ metadata\ + \ \n \t{schema|table}.owner\ + \ \n \t\t owner of a schema has: read-write + drop (any) table\ + \ \n \t\t owner of a table has: read-write + drop table\ + \ \n \t\t owner of a schema: change permissions on schema and all tables\ + \ \n \t\t owner of a table: change permissions on table\ + \ \n\ + \ Group URIs are in the format specified by the IVOA GMS\ + \ Recommendation: {resourceID}?{groupName}:\ + \ \n\ + \ \n \t\t{resourceID} is a registered GMS service\ + \ \n \t\t{groupName} is a group managed by that service\ + \ \n\ + \ e.g. ivo://cadc.nrc.ca/gms?CADC" servers: - url: /youcat paths: - /async: - post: - tags: - - TAP - summary: IVOA TAP v1.1 - description: | - TAP asynchronous query endpoint (create UWS Job) - parameters: - - name: LANG - in: query - description: specify the query language used in the QUERY parameter - required: true - schema: - type: string - - name: QUERY - in: query - description: specify the query - required: true - schema: - type: string - - name: FORMAT - in: query - description: "supported for backwards compatibility to 1.0 (see: RESPONSEFORMAT)" - schema: - type: string - - name: RESPONSEFORMAT - in: query - description: select output table format - schema: - type: string - - name: MAXREC - in: query - description: request a specific limit on number of rows to return - schema: - type: integer - format: int64 - - name: DEST - in: query - description: specify destination where output should be written (VOSpace URI) - schema: - type: string - format: uri - - name: UPLOAD - in: query - description: "specify name,location pair for a table to be uploaded and used\ - \ in the query" - schema: - type: string - responses: - "200": - description: Successful response - content: {} - "303": - description: standard UWS redirect to the created job - content: {} - "401": - description: Unauthorized - User not authenticated - content: {} - "403": - description: Permission Denied - Table(s) not readable - content: {} - "404": - description: Not Found - Table(s) not found - content: {} - "500": - description: Internal error - content: {} - "503": - description: Service busy - content: {} - default: - description: Unexpeced error - content: - text/xml: - schema: - $ref: '#/components/schemas/Error' - /sync: - get: - tags: - - TAP - summary: IVOA TAP v1.1 - description: | - TAP synchronous query endpoint - parameters: - - name: LANG - in: query - description: specify the query language used in the QUERY parameter - required: true - schema: - type: string - - name: QUERY - in: query - description: specify the query - required: true - schema: - type: string - - name: FORMAT - in: query - description: "supported for backwards compatibility to 1.0 (see: RESPONSEFORMAT)" - schema: - type: string - - name: RESPONSEFORMAT - in: query - description: select output table format - schema: - type: string - - name: MAXREC - in: query - description: request a specific limit on number of rows to return - schema: - type: integer - format: int64 - - name: UPLOAD - in: query - description: "specify name,location pair for a table to be uploaded and used\ - \ in the query" - schema: - type: string - responses: - "200": - description: Successful response - content: {} - "401": - description: Unauthorized - User not authenticated - content: {} - "403": - description: Permission Denied - Table(s) not readable - content: {} - "404": - description: Not Found - Table(s) not found - content: {} - "500": - description: Internal error - content: {} - "503": - description: Service busy - content: {} - default: - description: Unexpeced error - content: - application/x-votable+/xml: - schema: - $ref: '#/components/schemas/Error' - post: - tags: - - TAP - summary: IVOA TAP v1.1 - description: | - TAP synchronous query endpoint - parameters: - - name: LANG - in: query - description: specify the query language used in the QUERY parameter - required: true - schema: - type: string - - name: QUERY - in: query - description: specify the query - required: true - schema: - type: string - - name: FORMAT - in: query - description: "supported for backwards compatibility to 1.0 (see: RESPONSEFORMAT)" - schema: - type: string - - name: RESPONSEFORMAT - in: query - description: select output table format - schema: - type: string - - name: MAXREC - in: query - description: request a specific limit on number of rows to return - schema: - type: integer - format: int64 - - name: UPLOAD - in: query - description: "specify name,location pair for a table to be uploaded and used\ - \ in the query" - schema: - type: string - responses: - "200": - description: Successful response - content: {} - "401": - description: Unauthorized - User not authenticated - content: {} - "403": - description: Permission denied - Table(s) not readable - content: {} - "404": - description: Not Found - Table(s) not found - content: {} - "500": - description: Internal error - content: {} - "503": - description: Service busy - content: {} - default: - description: Unexpeced error - content: - application/x-votable+/xml: - schema: - $ref: '#/components/schemas/Error' - /availability: - get: - tags: - - Support Interfaces - summary: VOSI Availability - description: "Indicates whether the service is operable and shows the reliability\ - \ of the service for extended and scheduled requests. If the query parameter\ - \ 'detail=min' is used, a light weight heart beat test will be performed.\ - \ The heart beat test returns status 200 if the service is available." - parameters: - - name: detail - in: query - description: "specifies heart beat to be used to check for availability of\ - \ this service, the value 'min' must be used, otherwise the full availability\ - \ test will be performed" - schema: - type: string - responses: - "200": - description: A VOSI availability document in XML. - content: - text/xml: - schema: - $ref: '#/components/schemas/availability' - default: - description: Unexpected error - content: - text/xml: - schema: - $ref: '#/components/schemas/Error' - /capabilities: - get: - tags: - - Support Interfaces - summary: VOSI Capabilities - description: "Provides the service metadata in the form of a list of Capability\ - \ descriptions. Each of these descriptions is an \nXML element that:\n
    \n\ -
  • states that the service provides a particular, IVOA-standard function;
    • \n\ -
  • lists the interfaces for invoking that function;
    • \n
  • records any\ - \ details of the implementation of the function that are not defined as default\ - \ or constant in the standard for that function.
    • \n
\n" - responses: - "200": - description: A VOSI Capabilities document in XML. - content: - text/xml: - schema: - $ref: '#/components/schemas/capabilities' - "500": - description: Internal server error - content: {} - "503": - description: Service too busy - content: {} - default: - description: Unexpected error - content: - text/xml: - schema: - $ref: '#/components/schemas/Error' - /tables: - get: - tags: - - Support Interfaces - summary: VOSI Tables - description: | - Provides the table metadata in the form of a TableSet descriptions. - responses: - "200": - description: A VOSI document in XML. - content: - text/xml: - schema: - $ref: '#/components/schemas/tables' - "500": - description: Internal server error - content: {} - "503": - description: Service too busy - content: {} - default: - description: Unexpected error - content: - text/xml: - schema: - $ref: '#/components/schemas/Error' - /tables/{name}: - get: - tags: - - Support Interfaces - summary: get table metadata (VOSI) - description: | - Provides the table metadata for a single table. - parameters: - - name: name - in: path - description: a single fully qualified table name (e.g. tap_schema.tables) - required: true - schema: - type: string - responses: - "200": - description: A VOSI
document in XML. - content: - text/xml: - schema: - $ref: '#/components/schemas/tables' - "500": - description: Internal server error - content: {} - "503": - description: Service too busy - content: {} - default: - description: Unexpected error - content: - text/xml: - schema: - $ref: '#/components/schemas/Error' - put: - tags: - - Custom Features - summary: create table - description: | - table description in VOSI table or VOTable (no rows) format - parameters: - - name: name - in: path - description: | - the fully qualified name of the table to create - required: true - schema: - type: string - responses: - "201": - description: table created - content: {} - "400": - description: create table failed due to invalid input - content: {} - "500": - description: Internal server error - content: {} - "503": - description: Service too busy - content: {} - default: - description: Unexpected error - content: - '*/*': - schema: - $ref: '#/components/schemas/Error' - delete: - tags: - - Custom Features - summary: drop table - parameters: - - name: name - in: path - description: the table to drop - required: true - schema: - type: string - responses: - "200": - description: table dropped - content: {} - "500": - description: Internal server error - content: {} - "503": - description: Service too busy - content: {} - default: - description: Unexpected error - content: - '*/*': - schema: - $ref: '#/components/schemas/Error' - /permissions/{name}: - get: - tags: - - Custom Features - summary: view schema or table permissions - description: | - View the owner, public flag, read group, and write group of a schema or table. - parameters: - - name: name - in: path - description: name of the schema or table to view. - required: true - schema: - type: string - responses: - "200": - description: successful request - content: {} - "400": - description: invalid syntax - content: {} - "500": - description: Internal server error - content: {} - "503": - description: Service too busy - content: {} - default: - description: Unexpected error - content: - '*/*': - schema: - $ref: '#/components/schemas/Error' - post: - tags: - - Custom Features - summary: modify schema or table permissions - description: | - Modify any of the public flag, readGroup or writeGroup of a schema or table. These operations are permitted by the owner of the schema and owners of the target tables. Parameters are in-line CFLF separated entries in key=value format. An example of a groupURI is ivo://cadc.nrc.ca/gms?myGroup - parameters: - - name: name - in: path - description: name of the schema or table to modify. - required: true - schema: - type: string - requestBody: - description: set or clear read/write group. rw-group=groupURI or rw-group= - to clear. group URI in format ivo://cadc.nrc.ca/gms?groupName - content: - text/plain: {} - required: false - responses: - "200": - description: permissions updated successfully - content: {} - "400": - description: invalid permission syntax - content: {} - "403": - description: Insufficient permission to change permissions - content: {} - "500": - description: Internal server error - content: {} - "503": - description: Service too busy - content: {} - default: - description: Unexpected error - content: - '*/*': - schema: - $ref: '#/components/schemas/Error' - x-codegen-request-body-name: rw-group - /load/{tableName}: - post: - tags: - - Custom Features - summary: sync streaming row insert - description: | - Bulk load rows and append to the table. This currently supports input data in CSV and TSV format (with header), and FITS Binary Tables - parameters: - - name: tableName - in: path - description: a single fully qualified table name (e.g. tap_schema.tables) - required: true - schema: - type: string - responses: - "200": - description: rows successfully inserted - content: - '*/*': - schema: - $ref: '#/components/schemas/tables' - "400": - description: insert rows failed due to invalid input - content: {} - "500": - description: Internal server error - content: {} - "503": - description: Service too busy - content: {} - default: - description: Unexpected error - content: - '*/*': - schema: - $ref: '#/components/schemas/Error' - /table-update: - post: - tags: - - Custom Features - summary: async table update (create UWS Job) - description: Asynchronous table update currently update supports index creation. - In future it will also support loading content (rows) from a remote location - (URI) - parameters: - - name: TABLE - in: query - description: "the table to update (TABLE={table name}): fully-qualified name\ - \ of the table to update" - required: true - schema: - type: string - - name: INDEX - in: query - description: "index a column (INDEX={column name}): value is the name of the\ - \ column to index; currently limited to single column only" - required: true - schema: - type: string - - name: UNIQUE - in: query - description: "create unique index (UNIQUE=true): use with INDEX={column name}\ - \ to make a unique index (default: false)" - schema: - type: boolean - responses: - "200": - description: Successful response - content: {} - "303": - description: standard UWS redirect to the created job - content: {} - "401": - description: Unauthorized - User not authenticated - content: {} - "404": - description: Not Found - User not found - content: {} - "500": - description: Internal error - content: {} - "503": - description: Service busy - content: {} - default: - description: Unexpeced error - content: - text/xml: - schema: - $ref: '#/components/schemas/Error' -components: - schemas: - Job: - type: string - availability: - type: object - properties: - available: - type: boolean - xml: - prefix: vosi - attribute: true - note: - type: string - xml: - prefix: vosi - attribute: true - xml: - name: availability - namespace: http://www.ivoa.net/xml/VOSIAvailability/v1.0 - prefix: vosi - tables: - type: object - properties: - available: - type: boolean - xml: - prefix: vosi - attribute: true - note: - type: string - xml: - prefix: vosi - attribute: true - xml: - namespace: http://www.ivoa.net/xml/VOSITables/v1.0 - prefix: vosi - capabilities: - type: object - xml: - namespace: http://www.ivoa.net/xml/VOSICapabilities/v1.0 - prefix: vosi - Error: - required: - - code - - message - type: object - properties: - code: - type: integer - format: int32 - message: - type: string + /sync: + $ref: ./paths/tap-sync.yaml + + /async: + $ref: ./paths/tap-async.yaml + /async/{jobID}: + #$ref: ./paths/uws-job.yaml + $ref: https://haproxy.cadc.dao.nrc.ca/site/vault/files/pdowler/openapi/uws-job.yaml + /async/{jobID}/phase: + #$ref: ./paths/uws-job-phase.yaml + $ref: https://haproxy.cadc.dao.nrc.ca/site/vault/files/pdowler/openapi/uws-job-phase.yaml + ## TODO: more resources under /async/{jobID} + + /load/{name}: + $ref: ./paths/tap-load.yaml + + /table-update: + $ref: ./paths/tap-table-update.yaml + /table-update/{jobID}: + $ref: https://haproxy.cadc.dao.nrc.ca/site/vault/files/pdowler/openapi/uws-job.yaml + /table-update/{jobID}/phase: + $ref: https://haproxy.cadc.dao.nrc.ca/site/vault/files/pdowler/openapi/uws-job-phase.yaml + /availability: + #$ref: ./paths/vosi-availability.yaml + $ref: https://haproxy.cadc.dao.nrc.ca/site/vault/files/pdowler/openapi/vosi-availability.yaml + /capabilities: + #$ref: ./paths/vosi-capabilities.yaml + $ref: https://haproxy.cadc.dao.nrc.ca/site/vault/files/pdowler/openapi/vosi-capabilities.yaml + /tables: + #$ref: ./paths/vosi-tableset.yaml + $ref: https://haproxy.cadc.dao.nrc.ca/site/vault/files/pdowler/openapi/vosi-tableset.yaml + /tables/{name}: + #$ref: ./paths/vosi-table.yaml + $ref: https://haproxy.cadc.dao.nrc.ca/site/vault/files/pdowler/openapi/vosi-table.yaml diff --git a/youcat/src/main/webapp/paths/tap-async.yaml b/youcat/src/main/webapp/paths/tap-async.yaml new file mode 100644 index 00000000..452c85db --- /dev/null +++ b/youcat/src/main/webapp/paths/tap-async.yaml @@ -0,0 +1,37 @@ +get: + summary: UWS 1.1 + description: async job listing + parameters: {} + responses: {} +post: + summary: TAP-async 1.1 + description: TAP asynchronous query endpoint (create UWS Job) + parameters: + - $ref: ../components/parameters/tap-lang.yaml + - $ref: ../components/parameters/tap-query.yaml + - $ref: ../components/parameters/tap-upload.yaml + - $ref: ../components/parameters/tap-format.yaml + - $ref: ../components/parameters/dali-maxrec.yaml + - $ref: ../components/parameters/dali-responseformat.yaml + responses: + "303": + description: standard UWS redirect to the created job + content: {} + "401": + description: not authenticated + content: {} + "403": + description: permission denied + content: {} + "404": + description: not found + content: {} + "500": + description: internal error + content: {} + "503": + description: service busy + content: {} + default: + description: unexpected error + content: {} diff --git a/youcat/src/main/webapp/paths/tap-load.yaml b/youcat/src/main/webapp/paths/tap-load.yaml new file mode 100644 index 00000000..59a6127f --- /dev/null +++ b/youcat/src/main/webapp/paths/tap-load.yaml @@ -0,0 +1,45 @@ +post: + summary: youcat bulk load + 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 + content: + text/tab-separated-values: {} + text/csv: {} + application/fits: {} + application/x-votable+xml: {} + responses: + "200": + description: successful response + content: {} + "400": + description: load data failed due to invalid input + "401": + description: authentication required and user not authenticated + content: {} + "403": + description: permission denied (to query schema or table) + content: {} + "404": + description: not found + content: {} + "500": + description: Internal error + content: {} + "503": + description: Service busy + content: {} + default: + description: Unexpeced error + content: {} + + + + \ No newline at end of file diff --git a/youcat/src/main/webapp/paths/tap-sync.yaml b/youcat/src/main/webapp/paths/tap-sync.yaml new file mode 100644 index 00000000..327a8683 --- /dev/null +++ b/youcat/src/main/webapp/paths/tap-sync.yaml @@ -0,0 +1,66 @@ +get: + summary: TAP-sync 1.1 + description: TAP synchronous query endpoint + parameters: + - $ref: ../components/parameters/tap-lang.yaml + - $ref: ../components/parameters/tap-query.yaml + - $ref: ../components/parameters/tap-upload.yaml + - $ref: ../components/parameters/tap-format.yaml + - $ref: ../components/parameters/dali-maxrec.yaml + - $ref: ../components/parameters/dali-responseformat.yaml + responses: + "200": + description: successful response + content: {} + "303": + description: redirect to the job result (optional) + "401": + description: authentication required and user not authenticated + content: {} + "403": + description: permission denied (to query schema or table) + content: {} + "404": + description: not found (schema or table used in query does not exist) + content: {} + "500": + description: Internal error + content: {} + "503": + description: Service busy + content: {} + default: + description: Unexpeced error + content: {} +post: + summary: TAP-sync 1.1 + description: TAP synchronous query endpoint + parameters: + - $ref: ../components/parameters/tap-lang.yaml + - $ref: ../components/parameters/tap-query.yaml + - $ref: ../components/parameters/tap-upload.yaml + - $ref: ../components/parameters/tap-format.yaml + - $ref: ../components/parameters/dali-maxrec.yaml + - $ref: ../components/parameters/dali-responseformat.yaml + responses: + "200": + description: Successful response + content: {} + "401": + description: Unauthorized - User not authenticated + content: {} + "403": + description: Permission denied - Table(s) not readable + content: {} + "404": + description: Not Found - Table(s) not found + content: {} + "500": + description: Internal error + content: {} + "503": + description: Service busy + content: {} + default: + description: Unexpeced error + content: {} diff --git a/youcat/src/main/webapp/paths/tap-table-update.yaml b/youcat/src/main/webapp/paths/tap-table-update.yaml new file mode 100644 index 00000000..a4b8da39 --- /dev/null +++ b/youcat/src/main/webapp/paths/tap-table-update.yaml @@ -0,0 +1,49 @@ +get: + summary: UWS 1.1 + description: async job listing + parameters: {} + responses: {} +post: + summary: TAP table-update 1.2 + description: TAP asynchronous table update (create UWS Job) + parameters: + - name: TABLE + in: query + description: a single table name as provided in tap_schema + required: true + schema: + type: string + - name: INDEX + in: query + description: create index operation; value is a column name in the table + required: false + schema: + type: string + - name: UNIQUE + in: query + description: qualifier for INDEX to create a unique index + required: false + schema: + type: boolean + responses: + "303": + description: standard UWS redirect to the created job + content: {} + "401": + description: not authenticated + content: {} + "403": + description: permission denied + content: {} + "404": + description: not found + content: {} + "500": + description: internal error + content: {} + "503": + description: service busy + content: {} + default: + description: unexpected error + content: {} diff --git a/youcat/src/main/webapp/paths/uws-job-phase.yaml b/youcat/src/main/webapp/paths/uws-job-phase.yaml new file mode 100644 index 00000000..4c93a394 --- /dev/null +++ b/youcat/src/main/webapp/paths/uws-job-phase.yaml @@ -0,0 +1,58 @@ +get: + summary: UWS 1.1 + description: job phase resource + responses: + "200": + description: successful response + content: {} + "401": + description: not authenticated + content: {} + "403": + description: permission denied + content: {} + "404": + description: not found + content: {} + "500": + description: internal error + content: {} + "503": + description: service busy + content: {} + default: + description: unexpected error + content: {} +post: + summary: UWS 1.1 + description: update job + parameters: + - name: PHASE + in: query + description: attempt to change the phase + required: true + schema: + type: string + enum: [ABORT, RUN] + responses: + "200": + description: Successful response + content: {} + "401": + description: Unauthorized - User not authenticated + content: {} + "403": + description: Permission denied - Table(s) not readable + content: {} + "404": + description: Not Found - Table(s) not found + content: {} + "500": + description: Internal error + content: {} + "503": + description: Service busy + content: {} + default: + description: Unexpeced error + content: {} \ No newline at end of file diff --git a/youcat/src/main/webapp/paths/uws-job.yaml b/youcat/src/main/webapp/paths/uws-job.yaml new file mode 100644 index 00000000..dfb1d540 --- /dev/null +++ b/youcat/src/main/webapp/paths/uws-job.yaml @@ -0,0 +1,31 @@ +get: + summary: UWS 1.1 + description: job resource + parameters: + - name: WAIT + in: query + description: wait for the specified time in seconds or until the phase changes + required: false + type: integer + responses: + "200": + description: successful response + content: {} + "401": + description: not authenticated + content: {} + "403": + description: permission denied + content: {} + "404": + description: not found + content: {} + "500": + description: internal error + content: {} + "503": + description: service busy + content: {} + default: + description: unexpected error + content: {} \ No newline at end of file diff --git a/youcat/src/main/webapp/paths/vosi-availability.yaml b/youcat/src/main/webapp/paths/vosi-availability.yaml new file mode 100644 index 00000000..c0ff2e10 --- /dev/null +++ b/youcat/src/main/webapp/paths/vosi-availability.yaml @@ -0,0 +1,31 @@ +get: + tag: support + summary: VOSI Availability + description: | + "Indicates whether the service is operable and shows the reliability\ + of the service for extended and scheduled requests. If the query parameter\ + 'detail=min' is used, a light weight heart beat test will be performed.\ + The heart beat test returns status 200 if the service is available." + parameters: + - name: detail + in: query + description: perform minimal heartbeat style check + schema: + type: string + responses: + "200": + description: A VOSI availability document in XML. + content: + text/xml: + schema: + $ref: '#/components/schemas/availability' + default: + description: Unexpected error + content: {} +components: + schemas: + availability: + type: object + xml: + namespace: http://www.ivoa.net/xml/VOSIAvailability/v1.0 + prefix: vosi diff --git a/youcat/src/main/webapp/paths/vosi-capabilities.yaml b/youcat/src/main/webapp/paths/vosi-capabilities.yaml new file mode 100644 index 00000000..5cd9ae8f --- /dev/null +++ b/youcat/src/main/webapp/paths/vosi-capabilities.yaml @@ -0,0 +1,27 @@ +get: + tag: support + summary: VOSI Capabilities + description: TBD + responses: + "200": + description: A VOSI Capabilities document in XML. + content: + text/xml: + schema: + $ref: '#/components/schemas/capabilities' + "500": + description: Internal server error + content: {} + "503": + description: Service too busy + content: {} + default: + description: Unexpected error + content: {} +components: + schemas: + capabilities: + type: object + xml: + namespace: http://www.ivoa.net/xml/VOSICapabilities/v1.0 + prefix: vosi diff --git a/youcat/src/main/webapp/paths/vosi-table.yaml b/youcat/src/main/webapp/paths/vosi-table.yaml new file mode 100644 index 00000000..556f81d8 --- /dev/null +++ b/youcat/src/main/webapp/paths/vosi-table.yaml @@ -0,0 +1,85 @@ +get: + tag: table metadata + summary: get table metadata + description: provides the table metadata for a single schema or table + parameters: + - name: name + in: path + description: a single schema name or table name as provided in tap_schema + required: true + schema: + type: string + responses: + "200": + description: "A VOSI
document in XML" + content: {} + "500": + description: Internal server error + content: {} + "503": + description: Service too busy + content: {} + default: + description: Unexpected error + content: {} +post: + tag: table metadata + summary: update table metadata + description: update the tap_schema metadata from description in VOSI table format + parameters: + - name: name + in: path + description: the fully qualified name of the table to create + required: true + schema: + type: string +put: + tag: table metadata + summary: create table + description: "create table from description in VOSI table format (stretch: VOTable with no rows)" + parameters: + - name: name + in: path + description: the fully qualified name of the table to create + required: true + schema: + type: string + responses: + "201": + description: table created + content: {} + "400": + description: create table failed due to invalid input + content: {} + "500": + description: Internal server error + content: {} + "503": + description: Service too busy + content: {} + default: + description: Unexpected error + content: {} +delete: + tag: table metadata + summary: drop table + parameters: + - name: name + in: path + description: the table to drop + required: true + schema: + type: string + responses: + "200": + description: table dropped + content: {} + "500": + description: Internal server error + content: {} + "503": + description: Service too busy + content: {} + default: + description: Unexpected error + content: {} diff --git a/youcat/src/main/webapp/paths/vosi-tableset.yaml b/youcat/src/main/webapp/paths/vosi-tableset.yaml new file mode 100644 index 00000000..dbde9a11 --- /dev/null +++ b/youcat/src/main/webapp/paths/vosi-tableset.yaml @@ -0,0 +1,32 @@ +get: + tag: table metadata + summary: VOSI Tables + description: Provides the table metadata in the form of a TableSet descriptions + parameters: + - name: DETAIL + in: query + description: level of detail requested + required: false + schema: + type: string + enum: [min, max] + responses: + "200": + description: "A VOSI document in XML" + content: {} + "500": + description: Internal server error + content: {} + "503": + description: Service too busy + content: {} + default: + description: Unexpected error + content: {} +components: + schemas: + tables: + type: object + xml: + namespace: http://www.ivoa.net/xml/VOSITables/v1.0 + prefix: vosi diff --git a/youcat/src/main/webapp/service.json b/youcat/src/main/webapp/service.json deleted file mode 100644 index 23e7099e..00000000 --- a/youcat/src/main/webapp/service.json +++ /dev/null @@ -1,772 +0,0 @@ -{ - "swagger": "2.0", - "info": { - "version": "1.0", - "title": "user-managed TAP service (youcat)", - "description": "This page contains technical API information.\n\nThis service implements the IVOA TAP-1.1 Recommendation plus extensions to support table creation and bulk loading of content.\n\nThe endpoints listed below support both anonymous and authenticated access (using client certificate or cookie).\n\n YouCat supports user management of permissions at both the schema and table level. A schema owner is set when a YouCat allocation is created by the service operator. Table owners are set to be the user who created the table. Owners can set a flag for anonymous reading and can set groups for read-only and read-write permissons.\n The following describes how the permissions are enforced on schemas and tables:\n\n \t{schema|table}.public = false|true\n \t\tallows querying via TAP API\n \t{schema|table|.read-only = NULL | {group URI}\n \t\tread-only permission on a schema: allows TAP API to expose table\n \t\tread-only permission on table: allows TAP API to expose content of a table\n \t{schema|table}.read-write = NULL | {group URI}\n \t\tread-write permissions on a schema: read-only + create table\n \t\tread-write permission on a table: read-only + create index, append rows, update (tap_schema) metadata\n \t{schema|table}.owner\n \t\towner of a schema has: read-write + drop (any) table\n \t\towner of a table has: read-write + drop table\n \t\towner of a schema: change permissions on schema and all tables\n \t\towner of a table: change permissions on table\n\nGroup URIs are in the format:\n\n \tivo://cadc.nrc.ca/gms?groupName" - }, - "schemes": [ - "https" - ], - "basePath": "/youcat", - "paths": { - "/async": { - "post": { - "summary": "IVOA TAP v1.1", - "tags": [ - "TAP" - ], - "description": "TAP asynchronous query endpoint (create UWS Job)\n", - "parameters": [ - { - "name": "LANG", - "in": "query", - "description": "specify the query language used in the QUERY parameter", - "required": true, - "type": "string" - }, - { - "name": "QUERY", - "in": "query", - "description": "specify the query", - "required": true, - "type": "string" - }, - { - "name": "FORMAT", - "in": "query", - "description": "supported for backwards compatibility to 1.0 (see: RESPONSEFORMAT)", - "required": false, - "type": "string" - }, - { - "name": "RESPONSEFORMAT", - "in": "query", - "description": "select output table format", - "required": false, - "type": "string" - }, - { - "name": "MAXREC", - "in": "query", - "description": "request a specific limit on number of rows to return", - "required": false, - "type": "integer", - "format": "int64" - }, - { - "name": "DEST", - "in": "query", - "description": "specify destination where output should be written (VOSpace URI)", - "required": false, - "type": "string", - "format": "uri" - }, - { - "name": "UPLOAD", - "in": "query", - "collectionFormat": "multi", - "description": "specify name,location pair for a table to be uploaded and used in the query", - "required": false, - "type": "string" - } - ], - "produces": [ - "text/xml" - ], - "responses": { - "200": { - "description": "Successful response" - }, - "303": { - "description": "standard UWS redirect to the created job" - }, - "401": { - "description": "Unauthorized - User not authenticated" - }, - "403": { - "description": "Permission Denied - Table(s) not readable" - }, - "404": { - "description": "Not Found - Table(s) not found" - }, - "500": { - "description": "Internal error" - }, - "503": { - "description": "Service busy" - }, - "default": { - "description": "Unexpeced error", - "schema": { - "$ref": "#/definitions/Error" - } - } - } - } - }, - "/sync": { - "get": { - "summary": "IVOA TAP v1.1", - "tags": [ - "TAP" - ], - "description": "TAP synchronous query endpoint\n", - "parameters": [ - { - "name": "LANG", - "in": "query", - "description": "specify the query language used in the QUERY parameter", - "required": true, - "type": "string" - }, - { - "name": "QUERY", - "in": "query", - "description": "specify the query", - "required": true, - "type": "string" - }, - { - "name": "FORMAT", - "in": "query", - "description": "supported for backwards compatibility to 1.0 (see: RESPONSEFORMAT)", - "required": false, - "type": "string" - }, - { - "name": "RESPONSEFORMAT", - "in": "query", - "description": "select output table format", - "required": false, - "type": "string" - }, - { - "name": "MAXREC", - "in": "query", - "description": "request a specific limit on number of rows to return", - "required": false, - "type": "integer", - "format": "int64" - }, - { - "name": "UPLOAD", - "in": "query", - "collectionFormat": "multi", - "description": "specify name,location pair for a table to be uploaded and used in the query", - "required": false, - "type": "string" - } - ], - "produces": [ - "application/x-votable+/xml" - ], - "responses": { - "200": { - "description": "Successful response" - }, - "401": { - "description": "Unauthorized - User not authenticated" - }, - "403": { - "description": "Permission Denied - Table(s) not readable" - }, - "404": { - "description": "Not Found - Table(s) not found" - }, - "500": { - "description": "Internal error" - }, - "503": { - "description": "Service busy" - }, - "default": { - "description": "Unexpeced error", - "schema": { - "$ref": "#/definitions/Error" - } - } - } - }, - "post": { - "summary": "IVOA TAP v1.1", - "tags": [ - "TAP" - ], - "description": "TAP synchronous query endpoint\n", - "parameters": [ - { - "name": "LANG", - "in": "query", - "description": "specify the query language used in the QUERY parameter", - "required": true, - "type": "string" - }, - { - "name": "QUERY", - "in": "query", - "description": "specify the query", - "required": true, - "type": "string" - }, - { - "name": "FORMAT", - "in": "query", - "description": "supported for backwards compatibility to 1.0 (see: RESPONSEFORMAT)", - "required": false, - "type": "string" - }, - { - "name": "RESPONSEFORMAT", - "in": "query", - "description": "select output table format", - "required": false, - "type": "string" - }, - { - "name": "MAXREC", - "in": "query", - "description": "request a specific limit on number of rows to return", - "required": false, - "type": "integer", - "format": "int64" - }, - { - "name": "UPLOAD", - "in": "query", - "collectionFormat": "multi", - "description": "specify name,location pair for a table to be uploaded and used in the query", - "required": false, - "type": "string" - } - ], - "produces": [ - "application/x-votable+/xml" - ], - "responses": { - "200": { - "description": "Successful response" - }, - "401": { - "description": "Unauthorized - User not authenticated" - }, - "403": { - "description": "Permission denied - Table(s) not readable" - }, - "404": { - "description": "Not Found - Table(s) not found" - }, - "500": { - "description": "Internal error" - }, - "503": { - "description": "Service busy" - }, - "default": { - "description": "Unexpeced error", - "schema": { - "$ref": "#/definitions/Error" - } - } - } - } - }, - "/availability": { - "get": { - "tags": [ - "Support Interfaces" - ], - "summary": "VOSI Availability", - "description": "Indicates whether the service is operable and shows the reliability of the service for extended and scheduled requests. If the query parameter 'detail=min' is used, a light weight heart beat test will be performed. The heart beat test returns status 200 if the service is available.", - "parameters": [ - { - "name": "detail", - "in": "query", - "description": "specifies heart beat to be used to check for availability of this service, the value 'min' must be used, otherwise the full availability test will be performed", - "required": false, - "type": "string" - } - ], - "produces": [ - "text/xml" - ], - "responses": { - "200": { - "description": "A VOSI availability document in XML.", - "schema": { - "$ref": "#/definitions/availability" - } - }, - "default": { - "description": "Unexpected error", - "schema": { - "$ref": "#/definitions/Error" - } - } - } - } - }, - "/capabilities": { - "get": { - "summary": "VOSI Capabilities", - "tags": [ - "Support Interfaces" - ], - "description": "Provides the service metadata in the form of a list of Capability descriptions. Each of these descriptions is an \nXML element that:\n
    \n
  • states that the service provides a particular, IVOA-standard function;
    • \n
  • lists the interfaces for invoking that function;
    • \n
  • records any details of the implementation of the function that are not defined as default or constant in the standard for that function.
    • \n
\n", - "produces": [ - "text/xml" - ], - "responses": { - "200": { - "description": "A VOSI Capabilities document in XML.", - "schema": { - "$ref": "#/definitions/capabilities" - } - }, - "500": { - "description": "Internal server error" - }, - "503": { - "description": "Service too busy" - }, - "default": { - "description": "Unexpected error", - "schema": { - "$ref": "#/definitions/Error" - } - } - } - } - }, - "/tables": { - "get": { - "summary": "VOSI Tables", - "tags": [ - "Support Interfaces" - ], - "description": "Provides the table metadata in the form of a TableSet descriptions.\n", - "produces": [ - "text/xml" - ], - "responses": { - "200": { - "description": "A VOSI document in XML.", - "schema": { - "$ref": "#/definitions/tables" - } - }, - "500": { - "description": "Internal server error" - }, - "503": { - "description": "Service too busy" - }, - "default": { - "description": "Unexpected error", - "schema": { - "$ref": "#/definitions/Error" - } - } - } - } - }, - "/tables/{name}": { - "get": { - "summary": "get table metadata (VOSI)", - "tags": [ - "Support Interfaces" - ], - "description": "Provides the table metadata for a single table.\n", - "parameters": [ - { - "name": "name", - "in": "path", - "description": "a single fully qualified table name (e.g. tap_schema.tables)", - "required": true, - "type": "string" - } - ], - "produces": [ - "text/xml" - ], - "responses": { - "200": { - "description": "A VOSI
document in XML.", - "schema": { - "$ref": "#/definitions/tables" - } - }, - "500": { - "description": "Internal server error" - }, - "503": { - "description": "Service too busy" - }, - "default": { - "description": "Unexpected error", - "schema": { - "$ref": "#/definitions/Error" - } - } - } - }, - "put": { - "summary": "create table", - "description": "table description in VOSI table or VOTable (no rows) format\n", - "tags": [ - "Custom Features" - ], - "parameters": [ - { - "name": "name", - "in": "path", - "description": "the fully qualified name of the table to create\n", - "required": true, - "type": "string" - } - ], - "consumes": [ - "text/xml", - "application/x-votable+xml" - ], - "responses": { - "201": { - "description": "table created" - }, - "400": { - "description": "create table failed due to invalid input" - }, - "500": { - "description": "Internal server error" - }, - "503": { - "description": "Service too busy" - }, - "default": { - "description": "Unexpected error", - "schema": { - "$ref": "#/definitions/Error" - } - } - } - }, - "delete": { - "summary": "drop table", - "tags": [ - "Custom Features" - ], - "parameters": [ - { - "name": "name", - "in": "path", - "description": "the table to drop", - "required": true, - "type": "string" - } - ], - "responses": { - "200": { - "description": "table dropped" - }, - "500": { - "description": "Internal server error" - }, - "503": { - "description": "Service too busy" - }, - "default": { - "description": "Unexpected error", - "schema": { - "$ref": "#/definitions/Error" - } - } - } - } - }, - "/permissions/{name}": { - "get": { - "summary": "view schema or table permissions", - "tags": [ - "Custom Features" - ], - "description": "View the owner, public flag, read group, and write group of a schema or table.\n", - "parameters": [ - { - "name": "name", - "in": "path", - "description": "name of the schema or table to view.", - "required": true, - "type": "string" - } - ], - "provides": [ - "text/plain" - ], - "responses": { - "200": { - "description": "successful request" - }, - "400": { - "description": "invalid syntax" - }, - "500": { - "description": "Internal server error" - }, - "503": { - "description": "Service too busy" - }, - "default": { - "description": "Unexpected error", - "schema": { - "$ref": "#/definitions/Error" - } - } - } - }, - "post": { - "summary": "modify schema or table permissions", - "tags": [ - "Custom Features" - ], - "description": "Modify any of the public flag, readGroup or writeGroup of a schema or table. These operations are permitted by the owner of the schema and owners of the target tables. Parameters are in-line CFLF separated entries in key=value format. An example of a groupURI is ivo://cadc.nrc.ca/gms?myGroup\n", - "parameters": [ - { - "name": "name", - "in": "path", - "description": "name of the schema or table to modify.", - "required": true, - "type": "string" - }, - { - "name": "public", - "in": "body", - "description": "public=true or public=false", - "required": false, - "type": "string" - }, - { - "name": "r-group", - "in": "body", - "description": "set or clear read group. r-group=groupURI or r-group= to clear. group URI in format ivo://cadc.nrc.ca/gms?groupName", - "required": false, - "type": "string" - }, - { - "name": "rw-group", - "in": "body", - "description": "set or clear read/write group. rw-group=groupURI or rw-group= to clear. group URI in format ivo://cadc.nrc.ca/gms?groupName", - "required": false, - "type": "string" - } - ], - "consumes": [ - "text/plain" - ], - "responses": { - "200": { - "description": "permissions updated successfully" - }, - "400": { - "description": "invalid permission syntax" - }, - "403": { - "description": "Insufficient permission to change permissions" - }, - "500": { - "description": "Internal server error" - }, - "503": { - "description": "Service too busy" - }, - "default": { - "description": "Unexpected error", - "schema": { - "$ref": "#/definitions/Error" - } - } - } - } - }, - "/load/{tableName}": { - "post": { - "summary": "sync streaming row insert", - "tags": [ - "Custom Features" - ], - "description": "Bulk load rows and append to the table. This currently supports input data in CSV and TSV format (with header), and FITS Binary Tables\n", - "parameters": [ - { - "name": "tableName", - "in": "path", - "description": "a single fully qualified table name (e.g. tap_schema.tables)", - "required": true, - "type": "string" - } - ], - "consumes": [ - "text/csv", - "text/tab-separated-values", - "application/fits" - ], - "responses": { - "200": { - "description": "rows successfully inserted", - "schema": { - "$ref": "#/definitions/tables" - } - }, - "400": { - "description": "insert rows failed due to invalid input" - }, - "500": { - "description": "Internal server error" - }, - "503": { - "description": "Service too busy" - }, - "default": { - "description": "Unexpected error", - "schema": { - "$ref": "#/definitions/Error" - } - } - } - } - }, - "/table-update": { - "post": { - "summary": "async table update (create UWS Job)", - "tags": [ - "Custom Features" - ], - "description": "Asynchronous table update currently update supports index creation. In future it will also support loading content (rows) from a remote location (URI)", - "parameters": [ - { - "name": "TABLE", - "in": "query", - "description": "the table to update (TABLE={table name}): fully-qualified name of the table to update", - "required": true, - "type": "string" - }, - { - "name": "INDEX", - "in": "query", - "description": "index a column (INDEX={column name}): value is the name of the column to index; currently limited to single column only", - "required": true, - "type": "string" - }, - { - "name": "UNIQUE", - "in": "query", - "description": "create unique index (UNIQUE=true): use with INDEX={column name} to make a unique index (default: false)", - "required": false, - "type": "boolean" - } - ], - "produces": [ - "text/xml" - ], - "responses": { - "200": { - "description": "Successful response" - }, - "303": { - "description": "standard UWS redirect to the created job" - }, - "401": { - "description": "Unauthorized - User not authenticated" - }, - "404": { - "description": "Not Found - User not found" - }, - "500": { - "description": "Internal error" - }, - "503": { - "description": "Service busy" - }, - "default": { - "description": "Unexpeced error", - "schema": { - "$ref": "#/definitions/Error" - } - } - } - } - } - }, - "definitions": { - "Job": { - "type": "string" - }, - "availability": { - "type": "object", - "xml": { - "name": "availability", - "namespace": "http://www.ivoa.net/xml/VOSIAvailability/v1.0", - "prefix": "vosi" - }, - "properties": { - "available": { - "type": "boolean", - "xml": { - "attribute": true, - "prefix": "vosi" - } - }, - "note": { - "type": "string", - "xml": { - "attribute": true, - "prefix": "vosi" - } - } - } - }, - "tables": { - "type": "object", - "xml": { - "namespace": "http://www.ivoa.net/xml/VOSITables/v1.0", - "prefix": "vosi" - }, - "properties": { - "available": { - "type": "boolean", - "xml": { - "attribute": true, - "prefix": "vosi" - } - }, - "note": { - "type": "string", - "xml": { - "attribute": true, - "prefix": "vosi" - } - } - } - }, - "capabilities": { - "type": "object", - "xml": { - "namespace": "http://www.ivoa.net/xml/VOSICapabilities/v1.0", - "prefix": "vosi" - } - }, - "Error": { - "required": [ - "code", - "message" - ], - "properties": { - "code": { - "type": "integer", - "format": "int32" - }, - "message": { - "type": "string" - } - } - } - } -} From 7d69203076527d1b1a0f1ee794f0f1d8a1a1eae3 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Tue, 10 Sep 2024 13:55:55 -0700 Subject: [PATCH 03/23] vosi openapi cleanup --- youcat/src/main/webapp/index.html | 1 + youcat/src/main/webapp/openapi.yaml | 35 ++++---- youcat/src/main/webapp/paths/tap-async.yaml | 21 +---- youcat/src/main/webapp/paths/tap-load.yaml | 54 ++++++------ youcat/src/main/webapp/paths/tap-sync.yaml | 39 +-------- .../main/webapp/paths/tap-table-update.yaml | 63 ++++++-------- .../src/main/webapp/paths/uws-job-phase.yaml | 48 ++--------- youcat/src/main/webapp/paths/uws-job.yaml | 21 +---- .../main/webapp/paths/vosi-availability.yaml | 70 +++++++++++----- .../main/webapp/paths/vosi-capabilities.yaml | 50 +++++++---- youcat/src/main/webapp/paths/vosi-table.yaml | 83 ++++++++++--------- .../src/main/webapp/paths/vosi-tableset.yaml | 33 ++++---- 12 files changed, 219 insertions(+), 299 deletions(-) diff --git a/youcat/src/main/webapp/index.html b/youcat/src/main/webapp/index.html index 37094d97..43662f29 100644 --- a/youcat/src/main/webapp/index.html +++ b/youcat/src/main/webapp/index.html @@ -20,6 +20,7 @@ url: "openapi.yaml", dom_id: "#swagger-ui", deepLinking: true, + validatorUrl: "none", presets: [ SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset diff --git a/youcat/src/main/webapp/openapi.yaml b/youcat/src/main/webapp/openapi.yaml index 6dc56ea9..73dac7ae 100644 --- a/youcat/src/main/webapp/openapi.yaml +++ b/youcat/src/main/webapp/openapi.yaml @@ -44,32 +44,35 @@ paths: /async: $ref: ./paths/tap-async.yaml /async/{jobID}: - #$ref: ./paths/uws-job.yaml - $ref: https://haproxy.cadc.dao.nrc.ca/site/vault/files/pdowler/openapi/uws-job.yaml + $ref: ./paths/uws-job.yaml + #$ref: https://haproxy.cadc.dao.nrc.ca/site/vault/files/pdowler/openapi/uws-job.yaml /async/{jobID}/phase: - #$ref: ./paths/uws-job-phase.yaml - $ref: https://haproxy.cadc.dao.nrc.ca/site/vault/files/pdowler/openapi/uws-job-phase.yaml + $ref: ./paths/uws-job-phase.yaml + #$ref: https://haproxy.cadc.dao.nrc.ca/site/vault/files/pdowler/openapi/uws-job-phase.yaml ## TODO: more resources under /async/{jobID} + /tables: + $ref: ./paths/vosi-tableset.yaml + #$ref: https://haproxy.cadc.dao.nrc.ca/site/vault/files/pdowler/openapi/vosi-tableset.yaml + /tables/{name}: + $ref: ./paths/vosi-table.yaml + #$ref: https://haproxy.cadc.dao.nrc.ca/site/vault/files/pdowler/openapi/vosi-table.yaml + /load/{name}: $ref: ./paths/tap-load.yaml /table-update: $ref: ./paths/tap-table-update.yaml /table-update/{jobID}: - $ref: https://haproxy.cadc.dao.nrc.ca/site/vault/files/pdowler/openapi/uws-job.yaml + $ref: ./paths/uws-job.yaml + #$ref: https://haproxy.cadc.dao.nrc.ca/site/vault/files/pdowler/openapi/uws-job.yaml /table-update/{jobID}/phase: - $ref: https://haproxy.cadc.dao.nrc.ca/site/vault/files/pdowler/openapi/uws-job-phase.yaml + $ref: ./paths/uws-job-phase.yaml + #$ref: https://haproxy.cadc.dao.nrc.ca/site/vault/files/pdowler/openapi/uws-job-phase.yaml /availability: - #$ref: ./paths/vosi-availability.yaml - $ref: https://haproxy.cadc.dao.nrc.ca/site/vault/files/pdowler/openapi/vosi-availability.yaml + $ref: ./paths/vosi-availability.yaml + #$ref: https://haproxy.cadc.dao.nrc.ca/site/vault/files/pdowler/openapi/vosi-availability.yaml /capabilities: - #$ref: ./paths/vosi-capabilities.yaml - $ref: https://haproxy.cadc.dao.nrc.ca/site/vault/files/pdowler/openapi/vosi-capabilities.yaml - /tables: - #$ref: ./paths/vosi-tableset.yaml - $ref: https://haproxy.cadc.dao.nrc.ca/site/vault/files/pdowler/openapi/vosi-tableset.yaml - /tables/{name}: - #$ref: ./paths/vosi-table.yaml - $ref: https://haproxy.cadc.dao.nrc.ca/site/vault/files/pdowler/openapi/vosi-table.yaml + $ref: ./paths/vosi-capabilities.yaml + #$ref: https://haproxy.cadc.dao.nrc.ca/site/vault/files/pdowler/openapi/vosi-capabilities.yaml diff --git a/youcat/src/main/webapp/paths/tap-async.yaml b/youcat/src/main/webapp/paths/tap-async.yaml index 452c85db..000e7194 100644 --- a/youcat/src/main/webapp/paths/tap-async.yaml +++ b/youcat/src/main/webapp/paths/tap-async.yaml @@ -15,23 +15,4 @@ post: - $ref: ../components/parameters/dali-responseformat.yaml responses: "303": - description: standard UWS redirect to the created job - content: {} - "401": - description: not authenticated - content: {} - "403": - description: permission denied - content: {} - "404": - description: not found - content: {} - "500": - description: internal error - content: {} - "503": - description: service busy - content: {} - default: - description: unexpected error - content: {} + description: standard UWS redirect to the created job \ No newline at end of file diff --git a/youcat/src/main/webapp/paths/tap-load.yaml b/youcat/src/main/webapp/paths/tap-load.yaml index 59a6127f..710fa86e 100644 --- a/youcat/src/main/webapp/paths/tap-load.yaml +++ b/youcat/src/main/webapp/paths/tap-load.yaml @@ -1,5 +1,5 @@ post: - summary: youcat bulk load + summary: bulk load or row data description: TAP synchronous bulk load endpoint parameters: - name: name @@ -10,36 +10,30 @@ post: type: string requestBody: required: true - content: - text/tab-separated-values: {} - text/csv: {} - application/fits: {} - application/x-votable+xml: {} + $ref: '#/components/schemas/tableRows' + responses: "200": - description: successful response - content: {} - "400": - description: load data failed due to invalid input - "401": - description: authentication required and user not authenticated - content: {} - "403": - description: permission denied (to query schema or table) - content: {} - "404": - description: not found - content: {} - "500": - description: Internal error - content: {} - "503": - description: Service busy - content: {} - default: - description: Unexpeced error - content: {} - - + 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/youcat/src/main/webapp/paths/tap-sync.yaml b/youcat/src/main/webapp/paths/tap-sync.yaml index 327a8683..a44bc371 100644 --- a/youcat/src/main/webapp/paths/tap-sync.yaml +++ b/youcat/src/main/webapp/paths/tap-sync.yaml @@ -11,27 +11,8 @@ get: responses: "200": description: successful response - content: {} "303": description: redirect to the job result (optional) - "401": - description: authentication required and user not authenticated - content: {} - "403": - description: permission denied (to query schema or table) - content: {} - "404": - description: not found (schema or table used in query does not exist) - content: {} - "500": - description: Internal error - content: {} - "503": - description: Service busy - content: {} - default: - description: Unexpeced error - content: {} post: summary: TAP-sync 1.1 description: TAP synchronous query endpoint @@ -45,22 +26,4 @@ post: responses: "200": description: Successful response - content: {} - "401": - description: Unauthorized - User not authenticated - content: {} - "403": - description: Permission denied - Table(s) not readable - content: {} - "404": - description: Not Found - Table(s) not found - content: {} - "500": - description: Internal error - content: {} - "503": - description: Service busy - content: {} - default: - description: Unexpeced error - content: {} + diff --git a/youcat/src/main/webapp/paths/tap-table-update.yaml b/youcat/src/main/webapp/paths/tap-table-update.yaml index a4b8da39..41ac2181 100644 --- a/youcat/src/main/webapp/paths/tap-table-update.yaml +++ b/youcat/src/main/webapp/paths/tap-table-update.yaml @@ -5,45 +5,32 @@ get: responses: {} post: summary: TAP table-update 1.2 - description: TAP asynchronous table update (create UWS Job) + description: TAP asynchronous table update (create UWS Job); can only specify one operation parameters: - - name: TABLE - in: query - description: a single table name as provided in tap_schema - required: true - schema: - type: string - - name: INDEX - in: query - description: create index operation; value is a column name in the table - required: false - schema: - type: string - - name: UNIQUE - in: query - description: qualifier for INDEX to create a unique index - required: false - schema: - type: boolean + - name: TABLE + in: query + description: a single table name as provided in tap_schema + required: true + schema: + type: string + - name: INDEX + in: query + description: create index operation; value is a column name in the table + required: false + schema: + type: string + - name: UNIQUE + in: query + description: qualifier for INDEX to create a unique index + required: false + schema: + type: boolean + - name: INGEST + in: query + description: ingest operation; ingest an existing database table into tap_schema + required: false + schema: + type: boolean responses: "303": description: standard UWS redirect to the created job - content: {} - "401": - description: not authenticated - content: {} - "403": - description: permission denied - content: {} - "404": - description: not found - content: {} - "500": - description: internal error - content: {} - "503": - description: service busy - content: {} - default: - description: unexpected error - content: {} diff --git a/youcat/src/main/webapp/paths/uws-job-phase.yaml b/youcat/src/main/webapp/paths/uws-job-phase.yaml index 4c93a394..68a67538 100644 --- a/youcat/src/main/webapp/paths/uws-job-phase.yaml +++ b/youcat/src/main/webapp/paths/uws-job-phase.yaml @@ -4,29 +4,10 @@ get: responses: "200": description: successful response - content: {} - "401": - description: not authenticated - content: {} - "403": - description: permission denied - content: {} - "404": - description: not found - content: {} - "500": - description: internal error - content: {} - "503": - description: service busy - content: {} - default: - description: unexpected error - content: {} post: - summary: UWS 1.1 - description: update job - parameters: + summary: UWS 1.1 + description: update job + parameters: - name: PHASE in: query description: attempt to change the phase @@ -34,25 +15,6 @@ post: schema: type: string enum: [ABORT, RUN] - responses: + responses: "200": - description: Successful response - content: {} - "401": - description: Unauthorized - User not authenticated - content: {} - "403": - description: Permission denied - Table(s) not readable - content: {} - "404": - description: Not Found - Table(s) not found - content: {} - "500": - description: Internal error - content: {} - "503": - description: Service busy - content: {} - default: - description: Unexpeced error - content: {} \ No newline at end of file + description: phase change successful diff --git a/youcat/src/main/webapp/paths/uws-job.yaml b/youcat/src/main/webapp/paths/uws-job.yaml index dfb1d540..601e9ca2 100644 --- a/youcat/src/main/webapp/paths/uws-job.yaml +++ b/youcat/src/main/webapp/paths/uws-job.yaml @@ -9,23 +9,4 @@ get: type: integer responses: "200": - description: successful response - content: {} - "401": - description: not authenticated - content: {} - "403": - description: permission denied - content: {} - "404": - description: not found - content: {} - "500": - description: internal error - content: {} - "503": - description: service busy - content: {} - default: - description: unexpected error - content: {} \ No newline at end of file + description: successful response \ No newline at end of file diff --git a/youcat/src/main/webapp/paths/vosi-availability.yaml b/youcat/src/main/webapp/paths/vosi-availability.yaml index c0ff2e10..5f0af6d2 100644 --- a/youcat/src/main/webapp/paths/vosi-availability.yaml +++ b/youcat/src/main/webapp/paths/vosi-availability.yaml @@ -1,31 +1,63 @@ +head: + tag: VOSI + summary: VOSI Availability heartbeat check + description: | + Perform a minimal check that the service is reachable and running. This + check is intended to be very fast and lightweight. + responses: + "200": + description: service is reachable + ## TBD: response code for read-only mode? off line mode? get: - tag: support - summary: VOSI Availability + tag: VOSI + summary: VOSI Availability full check description: | - "Indicates whether the service is operable and shows the reliability\ - of the service for extended and scheduled requests. If the query parameter\ - 'detail=min' is used, a light weight heart beat test will be performed.\ - The heart beat test returns status 200 if the service is available." - parameters: - - name: detail - in: query - description: perform minimal heartbeat style check - schema: - type: string - responses: + Perform a complete check that the service is operational. This normally + includes checking the availability of back end resources (e.g. database, + storage, ...) and that other services that this service depends on (e.g. AAI + services) are reachable (via heartbeat availability check). + responses: "200": description: A VOSI availability document in XML. content: text/xml: schema: $ref: '#/components/schemas/availability' + ## TBD: different response code for read-only mode? off line mode? default: description: Unexpected error content: {} +post: + tag: VOSI + summary: (CADC extension) modify the state (availability) of a running service + description: | + An operator can modify the state of a service instance to put it into one of + three modes: offline, read-only, and read-write (normal). The detailed meaning of + these modes depends on the nature of the service. + parameters: + - name: STATE + in: query + description: new service state + required: true + schema: + type: string + enum: [ReadWrite, ReadOnly, Offline] + responses: + "204": + description: service state updated + "401": + description: authentication required or attempted authentication failed + "403": + description: permission denied + components: - schemas: - availability: - type: object - xml: - namespace: http://www.ivoa.net/xml/VOSIAvailability/v1.0 - prefix: vosi + schemas: + availability: + content: + text/xml: + schema: + type: object + xml: + name: availability + prefix: vosi + namespace: http://www.ivoa.net/xml/VOSIAvailability/v1.0 diff --git a/youcat/src/main/webapp/paths/vosi-capabilities.yaml b/youcat/src/main/webapp/paths/vosi-capabilities.yaml index 5cd9ae8f..7afe32bc 100644 --- a/youcat/src/main/webapp/paths/vosi-capabilities.yaml +++ b/youcat/src/main/webapp/paths/vosi-capabilities.yaml @@ -1,7 +1,24 @@ +head: + tag: VOSI + summary: VOSI Capabilities + description: | + Get standard headers for the service. The standard headers should include + AAI related headers (www-authenticate challenges or x-vo-authenticated + indicator) if applicable, server name and version info, and other + applicable header information. SSO-next: clients use this operation to probe + for available authentiction methods. + responses: + "200": + description: successful probe, service allows request from caller + "401": + description: | + successful probe, service requires authentication or attempted authentication failed + "403": + description: authentication succeed, caller is not permitted to make requests get: - tag: support + tag: VOSI summary: VOSI Capabilities - description: TBD + description: Get the set of VOResource capability descriptions for this service. responses: "200": description: A VOSI Capabilities document in XML. @@ -9,19 +26,18 @@ get: text/xml: schema: $ref: '#/components/schemas/capabilities' - "500": - description: Internal server error - content: {} - "503": - description: Service too busy - content: {} - default: - description: Unexpected error - content: {} + "401": + description: service requires authentication or attempted authentication failed + "403": + description: authentication succeed, caller is not permitted to make any request components: - schemas: - capabilities: - type: object - xml: - namespace: http://www.ivoa.net/xml/VOSICapabilities/v1.0 - prefix: vosi + schemas: + capabilities: + content: + text/xml: + schema: + type: object + xml: + name: capabilities + prefix: vosi + namespace: http://www.ivoa.net/xml/VOSICapabilities/v1.0 diff --git a/youcat/src/main/webapp/paths/vosi-table.yaml b/youcat/src/main/webapp/paths/vosi-table.yaml index 556f81d8..1fe13fe2 100644 --- a/youcat/src/main/webapp/paths/vosi-table.yaml +++ b/youcat/src/main/webapp/paths/vosi-table.yaml @@ -1,6 +1,6 @@ get: - tag: table metadata - summary: get table metadata + tag: VOSI + summary: get metadata for the specified table description: provides the table metadata for a single schema or table parameters: - name: name @@ -11,21 +11,14 @@ get: type: string responses: "200": - description: "A VOSI
document in XML" - content: {} - "500": - description: Internal server error - content: {} - "503": - description: Service too busy - content: {} - default: - description: Unexpected error - content: {} + description: metadata for the specified table + $ref: '#/components/schemas/tableDoc' post: - tag: table metadata + tag: VOSI summary: update table metadata - description: update the tap_schema metadata from description in VOSI table format + description: | + update the tap_schema metadata from description; + TBD: what can be changed and what is immutable? parameters: - name: name in: path @@ -33,10 +26,17 @@ post: required: true schema: type: string + requestBody: + $ref: '#/components/schemas/tableDoc' + responses: + "204": + description: table updated + "400": + description: update table metadata failed due to invalid input put: - tag: table metadata + tag: VOSI summary: create table - description: "create table from description in VOSI table format (stretch: VOTable with no rows)" + description: create table from description parameters: - name: name in: path @@ -44,6 +44,8 @@ put: required: true schema: type: string + requestBody: + $ref: '#/components/schemas/tableDoc' responses: "201": description: table created @@ -51,35 +53,36 @@ put: "400": description: create table failed due to invalid input content: {} - "500": - description: Internal server error - content: {} - "503": - description: Service too busy - content: {} - default: - description: Unexpected error - content: {} delete: - tag: table metadata - summary: drop table + tag: VOSI + summary: delete table parameters: - name: name in: path - description: the table to drop + description: | + the table to delete; + TBD: remove from tap_schema and drop from db? required: true schema: type: string responses: - "200": + "204": description: table dropped - content: {} - "500": - description: Internal server error - content: {} - "503": - description: Service too busy - content: {} - default: - description: Unexpected error - content: {} + +components: + schemas: + tableDoc: + content: + text/xml: + schema: + type: object + xml: + name: table + prefix: vosi + namespace: http://www.ivoa.net/xml/VOSITables/v1.0 +# 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/youcat/src/main/webapp/paths/vosi-tableset.yaml b/youcat/src/main/webapp/paths/vosi-tableset.yaml index dbde9a11..a1474e0f 100644 --- a/youcat/src/main/webapp/paths/vosi-tableset.yaml +++ b/youcat/src/main/webapp/paths/vosi-tableset.yaml @@ -1,7 +1,8 @@ get: + tag: VOSI tag: table metadata summary: VOSI Tables - description: Provides the table metadata in the form of a TableSet descriptions + description: Provides the table metadata in the form of a TableSet description parameters: - name: DETAIL in: query @@ -12,21 +13,17 @@ get: enum: [min, max] responses: "200": - description: "A VOSI document in XML" - content: {} - "500": - description: Internal server error - content: {} - "503": - description: Service too busy - content: {} - default: - description: Unexpected error - content: {} + description: metadata for schemas and tables + $ref: '#/components/schemas/tablesetDoc' components: - schemas: - tables: - type: object - xml: - namespace: http://www.ivoa.net/xml/VOSITables/v1.0 - prefix: vosi + schemas: + tablesetDoc: + content: + text/xml: + schema: + type: object + xml: + name: tableset + prefix: vosi + namespace: http://www.ivoa.net/xml/VOSITables/v1.0 + From 944f57a26a04f34e61d94629a19091da2ba53f99 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Thu, 12 Sep 2024 11:29:10 -0700 Subject: [PATCH 04/23] start on reusable response descriptions --- .../main/webapp/components/std-responses.yaml | 19 ++++++ .../main/webapp/components/tap-responses.yaml | 7 +++ .../main/webapp/components/uws-responses.yaml | 37 +++++++++++ youcat/src/main/webapp/paths/tap-async.yaml | 18 ++++-- youcat/src/main/webapp/paths/tap-sync.yaml | 26 ++++++-- .../src/main/webapp/paths/uws-job-phase.yaml | 14 ++++- youcat/src/main/webapp/paths/uws-job.yaml | 11 +++- .../main/webapp/paths/vosi-availability.yaml | 20 +++--- .../main/webapp/paths/vosi-capabilities.yaml | 16 ++--- youcat/src/main/webapp/paths/vosi-table.yaml | 61 +++++++++++++------ .../src/main/webapp/paths/vosi-tableset.yaml | 10 ++- 11 files changed, 181 insertions(+), 58 deletions(-) create mode 100644 youcat/src/main/webapp/components/std-responses.yaml create mode 100644 youcat/src/main/webapp/components/tap-responses.yaml create mode 100644 youcat/src/main/webapp/components/uws-responses.yaml diff --git a/youcat/src/main/webapp/components/std-responses.yaml b/youcat/src/main/webapp/components/std-responses.yaml new file mode 100644 index 00000000..b5f70735 --- /dev/null +++ b/youcat/src/main/webapp/components/std-responses.yaml @@ -0,0 +1,19 @@ +# UWS create job response +not-authenticated: + description: authentication is required and current attempt failed + headers: + www-authenticate: + schema: + type: string +permission-denied: + description: caller not allowed to perform operation + content: + text/plain: + schema: + type: string +not-found: + description: resource not found + content: + text/plain: + schema: + type: string \ No newline at end of file diff --git a/youcat/src/main/webapp/components/tap-responses.yaml b/youcat/src/main/webapp/components/tap-responses.yaml new file mode 100644 index 00000000..cc11415d --- /dev/null +++ b/youcat/src/main/webapp/components/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/youcat/src/main/webapp/components/uws-responses.yaml b/youcat/src/main/webapp/components/uws-responses.yaml new file mode 100644 index 00000000..1008b197 --- /dev/null +++ b/youcat/src/main/webapp/components/uws-responses.yaml @@ -0,0 +1,37 @@ +# UWS create job response +created: + description: standard UWS 1.1 redirect to the created job URL + headers: + location: + schema: + type: string + format: uri +invalid-phase-change: + description: the requested phase change is invalid + content: + text/plain: + schema: + type: string +job-listing: + description: list of jobs owned by the caller + content: + text/xml: + schema: + type: object + xml: + name: jobs + prefix: uws + namespace: http://www.ivoa.net/xml/UWS/v1.0 + +components: + schemas: + jobDoc: + content: + text/xml: + schema: + type: object + xml: + name: job + prefix: uws + namespace: http://www.ivoa.net/xml/UWS/v1.0 + \ No newline at end of file diff --git a/youcat/src/main/webapp/paths/tap-async.yaml b/youcat/src/main/webapp/paths/tap-async.yaml index 000e7194..4d94ff5c 100644 --- a/youcat/src/main/webapp/paths/tap-async.yaml +++ b/youcat/src/main/webapp/paths/tap-async.yaml @@ -1,8 +1,14 @@ get: summary: UWS 1.1 description: async job listing - parameters: {} - responses: {} + parameters: + responses: + 200: + $ref: ../components/uws-responses.yaml#/job-listing + 401: + $ref: ../components/std-responses.yaml#/not-authenticated + 403: + $ref: ../components/std-responses.yaml#/permission-denied post: summary: TAP-async 1.1 description: TAP asynchronous query endpoint (create UWS Job) @@ -14,5 +20,9 @@ post: - $ref: ../components/parameters/dali-maxrec.yaml - $ref: ../components/parameters/dali-responseformat.yaml responses: - "303": - description: standard UWS redirect to the created job \ No newline at end of file + 303: + $ref: ../components/uws-responses.yaml#/created + 401: + $ref: ../components/std-responses.yaml#/not-authenticated + 403: + $ref: ../components/std-responses.yaml#/permission-denied diff --git a/youcat/src/main/webapp/paths/tap-sync.yaml b/youcat/src/main/webapp/paths/tap-sync.yaml index a44bc371..ce077e2c 100644 --- a/youcat/src/main/webapp/paths/tap-sync.yaml +++ b/youcat/src/main/webapp/paths/tap-sync.yaml @@ -9,10 +9,16 @@ get: - $ref: ../components/parameters/dali-maxrec.yaml - $ref: ../components/parameters/dali-responseformat.yaml responses: - "200": - description: successful response - "303": - description: redirect to the job result (optional) + 200: + description: successful response + 303: + description: redirect to the job result (optional) + 400: + $ref: ../components/tap-responses.yaml#/invalid-query + 401: + $ref: ../components/std-responses.yaml#/not-authenticated + 403: + $ref: ../components/std-responses.yaml#/permission-denied post: summary: TAP-sync 1.1 description: TAP synchronous query endpoint @@ -24,6 +30,14 @@ post: - $ref: ../components/parameters/dali-maxrec.yaml - $ref: ../components/parameters/dali-responseformat.yaml responses: - "200": - description: Successful response + 200: + description: successful response + 303: + description: redirect to the job result (optional) + 400: + $ref: ../components/tap-responses.yaml#/invalid-query + 401: + $ref: ../components/std-responses.yaml#/not-authenticated + 403: + $ref: ../components/std-responses.yaml#/permission-denied diff --git a/youcat/src/main/webapp/paths/uws-job-phase.yaml b/youcat/src/main/webapp/paths/uws-job-phase.yaml index 68a67538..d60be73c 100644 --- a/youcat/src/main/webapp/paths/uws-job-phase.yaml +++ b/youcat/src/main/webapp/paths/uws-job-phase.yaml @@ -2,7 +2,7 @@ get: summary: UWS 1.1 description: job phase resource responses: - "200": + 200: description: successful response post: summary: UWS 1.1 @@ -16,5 +16,13 @@ post: type: string enum: [ABORT, RUN] responses: - "200": - description: phase change successful + 200: + description: phase change successful + 400: + $ref: ../components/uws-responses.yaml#/invalid-phase-change + 401: + $ref: ../components/std-responses.yaml#/not-authenticated + 403: + $ref: ../components/std-responses.yaml#/permission-denied + 404: + $ref: ../components/std-responses.yaml#/not-found \ No newline at end of file diff --git a/youcat/src/main/webapp/paths/uws-job.yaml b/youcat/src/main/webapp/paths/uws-job.yaml index 601e9ca2..4ae7db5a 100644 --- a/youcat/src/main/webapp/paths/uws-job.yaml +++ b/youcat/src/main/webapp/paths/uws-job.yaml @@ -8,5 +8,12 @@ get: required: false type: integer responses: - "200": - description: successful response \ No newline at end of file + 200: + description: successful response + $ref: '../components/uws-responses.yaml#/components/schemas/jobDoc' + 401: + $ref: ../components/std-responses.yaml#/not-authenticated + 403: + $ref: ../components/std-responses.yaml#/permission-denied + 404: + $ref: ../components/std-responses.yaml#/not-found diff --git a/youcat/src/main/webapp/paths/vosi-availability.yaml b/youcat/src/main/webapp/paths/vosi-availability.yaml index 5f0af6d2..ec17090e 100644 --- a/youcat/src/main/webapp/paths/vosi-availability.yaml +++ b/youcat/src/main/webapp/paths/vosi-availability.yaml @@ -5,7 +5,7 @@ head: Perform a minimal check that the service is reachable and running. This check is intended to be very fast and lightweight. responses: - "200": + 200: description: service is reachable ## TBD: response code for read-only mode? off line mode? get: @@ -17,16 +17,12 @@ get: storage, ...) and that other services that this service depends on (e.g. AAI services) are reachable (via heartbeat availability check). responses: - "200": + 200: description: A VOSI availability document in XML. content: text/xml: schema: $ref: '#/components/schemas/availability' - ## TBD: different response code for read-only mode? off line mode? - default: - description: Unexpected error - content: {} post: tag: VOSI summary: (CADC extension) modify the state (availability) of a running service @@ -43,12 +39,12 @@ post: type: string enum: [ReadWrite, ReadOnly, Offline] responses: - "204": - description: service state updated - "401": - description: authentication required or attempted authentication failed - "403": - description: permission denied + 204: + description: service state updated + 401: + $ref: ../components/std-responses.yaml#/not-authenticated + 403: + $ref: ../components/std-responses.yaml#/permission-denied components: schemas: diff --git a/youcat/src/main/webapp/paths/vosi-capabilities.yaml b/youcat/src/main/webapp/paths/vosi-capabilities.yaml index 7afe32bc..0c4033be 100644 --- a/youcat/src/main/webapp/paths/vosi-capabilities.yaml +++ b/youcat/src/main/webapp/paths/vosi-capabilities.yaml @@ -8,28 +8,28 @@ head: applicable header information. SSO-next: clients use this operation to probe for available authentiction methods. responses: - "200": + 200: description: successful probe, service allows request from caller - "401": + 401: description: | successful probe, service requires authentication or attempted authentication failed - "403": + 403: description: authentication succeed, caller is not permitted to make requests get: tag: VOSI summary: VOSI Capabilities description: Get the set of VOResource capability descriptions for this service. responses: - "200": + 200: description: A VOSI Capabilities document in XML. content: text/xml: schema: $ref: '#/components/schemas/capabilities' - "401": - description: service requires authentication or attempted authentication failed - "403": - description: authentication succeed, caller is not permitted to make any request + 401: + $ref: ../components/std-responses.yaml#/not-authenticated + 403: + $ref: ../components/std-responses.yaml#/permission-denied components: schemas: capabilities: diff --git a/youcat/src/main/webapp/paths/vosi-table.yaml b/youcat/src/main/webapp/paths/vosi-table.yaml index 1fe13fe2..0fdb2f19 100644 --- a/youcat/src/main/webapp/paths/vosi-table.yaml +++ b/youcat/src/main/webapp/paths/vosi-table.yaml @@ -1,5 +1,4 @@ get: - tag: VOSI summary: get metadata for the specified table description: provides the table metadata for a single schema or table parameters: @@ -10,12 +9,17 @@ get: schema: type: string responses: - "200": - description: metadata for the specified table - $ref: '#/components/schemas/tableDoc' + 200: + description: metadata for the specified table + $ref: '#/components/schemas/tableDoc' + 401: + $ref: ../components/std-responses.yaml#/not-authenticated + 403: + $ref: ../components/std-responses.yaml#/permission-denied + 404: + $ref: ../components/std-responses.yaml#/not-found post: - tag: VOSI - summary: update table metadata + summary: proto - update table metadata description: | update the tap_schema metadata from description; TBD: what can be changed and what is immutable? @@ -25,17 +29,24 @@ post: description: the fully qualified name of the table to create required: true schema: - type: string + type: string requestBody: $ref: '#/components/schemas/tableDoc' responses: - "204": + 204: description: table updated - "400": + 400: description: update table metadata failed due to invalid input + content: + text/plain: + 401: + $ref: ../components/std-responses.yaml#/not-authenticated + 403: + $ref: ../components/std-responses.yaml#/permission-denied + 404: + $ref: ../components/std-responses.yaml#/not-found put: - tag: VOSI - summary: create table + summary: proto - create table description: create table from description parameters: - name: name @@ -47,15 +58,20 @@ put: requestBody: $ref: '#/components/schemas/tableDoc' responses: - "201": + 201: description: table created - content: {} - "400": - description: create table failed due to invalid input - content: {} + 400: + description: create table failed due to invalid input + content: + text/plain: + 401: + $ref: ../components/std-responses.yaml#/not-authenticated + 403: + $ref: ../components/std-responses.yaml#/permission-denied + 404: + $ref: ../components/std-responses.yaml#/not-found delete: - tag: VOSI - summary: delete table + summary: proto - delete table parameters: - name: name in: path @@ -66,9 +82,14 @@ delete: schema: type: string responses: - "204": + 204: description: table dropped - + 401: + $ref: ../components/std-responses.yaml#/not-authenticated + 403: + $ref: ../components/std-responses.yaml#/permission-denied + 404: + $ref: ../components/std-responses.yaml#/not-found components: schemas: tableDoc: diff --git a/youcat/src/main/webapp/paths/vosi-tableset.yaml b/youcat/src/main/webapp/paths/vosi-tableset.yaml index a1474e0f..8c4218de 100644 --- a/youcat/src/main/webapp/paths/vosi-tableset.yaml +++ b/youcat/src/main/webapp/paths/vosi-tableset.yaml @@ -12,9 +12,13 @@ get: type: string enum: [min, max] responses: - "200": - description: metadata for schemas and tables - $ref: '#/components/schemas/tablesetDoc' + 200: + description: metadata for schemas and tables + $ref: '#/components/schemas/tablesetDoc' + 401: + $ref: ../components/std-responses.yaml#/not-authenticated + 403: + $ref: ../components/std-responses.yaml#/permission-denied components: schemas: tablesetDoc: From 0cb03bd1f4ef7fe179e851470732cb77698bdb0d Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Fri, 4 Oct 2024 10:59:34 -0700 Subject: [PATCH 05/23] minor openapi tweaks --- .../main/webapp/components/std-responses.yaml | 2 +- .../main/webapp/components/uws-responses.yaml | 3 +- youcat/src/main/webapp/openapi.yaml | 45 ++++--------------- .../main/webapp/paths/tap-table-update.yaml | 16 +++++-- 4 files changed, 23 insertions(+), 43 deletions(-) diff --git a/youcat/src/main/webapp/components/std-responses.yaml b/youcat/src/main/webapp/components/std-responses.yaml index b5f70735..3538f635 100644 --- a/youcat/src/main/webapp/components/std-responses.yaml +++ b/youcat/src/main/webapp/components/std-responses.yaml @@ -16,4 +16,4 @@ not-found: content: text/plain: schema: - type: string \ No newline at end of file + type: string diff --git a/youcat/src/main/webapp/components/uws-responses.yaml b/youcat/src/main/webapp/components/uws-responses.yaml index 1008b197..632d433f 100644 --- a/youcat/src/main/webapp/components/uws-responses.yaml +++ b/youcat/src/main/webapp/components/uws-responses.yaml @@ -33,5 +33,4 @@ components: xml: name: job prefix: uws - namespace: http://www.ivoa.net/xml/UWS/v1.0 - \ No newline at end of file + namespace: http://www.ivoa.net/xml/UWS/v1.0 diff --git a/youcat/src/main/webapp/openapi.yaml b/youcat/src/main/webapp/openapi.yaml index 73dac7ae..6ab7ef6d 100644 --- a/youcat/src/main/webapp/openapi.yaml +++ b/youcat/src/main/webapp/openapi.yaml @@ -2,39 +2,7 @@ openapi: 3.1.0 info: title: user-managed TAP service (youcat) version: "1.0" - description: "This page contains technical API information.\n\nThis service implements\ - \ the IVOA TAP-1.1\ - \ Recommendation plus extensions to support table creation and bulk loading of\ - \ content.\n\nThe endpoints listed below support both anonymous and authenticated\ - \ access (using client certificate or cookie).\n\n YouCat supports user management\ - \ of permissions at both the schema and table level. A schema owner is set when\ - \ a YouCat allocation is created by the service operator. Table owners are set\ - \ to be the user who created the table. Owners can set a flag for anonymous reading\ - \ and can set groups for read-only and read-write permissons.\n The following\ - \ describes how the permissions are enforced on schemas and tables:\ - \ \n\ - \ \n \t{schema|table}.public = false|true\ - \ \n \t\t allows querying via TAP API\ - \ \n \t{schema|table|.read-only = NULL | {group URI}\ - \ \n \t\t read-only permission on a schema: allows TAP API to expose table\ - \ \n \t\t read-only permission on table: allows TAP API to expose the content of a table\ - \ \n \t{schema|table}.read-write = NULL | {group URI}\ - \ \n \t\t read-write permissions on a schema: read-only + create table\ - \ \n \t\t read-write permission on a table: read-only + create index, append rows, update (tap_schema)\ - \ metadata\ - \ \n \t{schema|table}.owner\ - \ \n \t\t owner of a schema has: read-write + drop (any) table\ - \ \n \t\t owner of a table has: read-write + drop table\ - \ \n \t\t owner of a schema: change permissions on schema and all tables\ - \ \n \t\t owner of a table: change permissions on table\ - \ \n\ - \ Group URIs are in the format specified by the IVOA GMS\ - \ Recommendation: {resourceID}?{groupName}:\ - \ \n\ - \ \n \t\t{resourceID} is a registered GMS service\ - \ \n \t\t{groupName} is a group managed by that service\ - \ \n\ - \ e.g. ivo://cadc.nrc.ca/gms?CADC" + description: This is more or less the current TAP-1.1 standard. servers: - url: /youcat paths: @@ -49,7 +17,7 @@ paths: /async/{jobID}/phase: $ref: ./paths/uws-job-phase.yaml #$ref: https://haproxy.cadc.dao.nrc.ca/site/vault/files/pdowler/openapi/uws-job-phase.yaml - ## TODO: more resources under /async/{jobID} + ## TODO: more resources under /async/{jobID}?? /tables: $ref: ./paths/vosi-tableset.yaml @@ -58,9 +26,6 @@ paths: $ref: ./paths/vosi-table.yaml #$ref: https://haproxy.cadc.dao.nrc.ca/site/vault/files/pdowler/openapi/vosi-table.yaml - /load/{name}: - $ref: ./paths/tap-load.yaml - /table-update: $ref: ./paths/tap-table-update.yaml /table-update/{jobID}: @@ -69,7 +34,13 @@ paths: /table-update/{jobID}/phase: $ref: ./paths/uws-job-phase.yaml #$ref: https://haproxy.cadc.dao.nrc.ca/site/vault/files/pdowler/openapi/uws-job-phase.yaml + ## TODO: more resources under /table-update/{jobID}?? + + /load/{name}: + $ref: ./paths/tap-load.yaml + ## TODO: set permissions + /availability: $ref: ./paths/vosi-availability.yaml #$ref: https://haproxy.cadc.dao.nrc.ca/site/vault/files/pdowler/openapi/vosi-availability.yaml diff --git a/youcat/src/main/webapp/paths/tap-table-update.yaml b/youcat/src/main/webapp/paths/tap-table-update.yaml index 41ac2181..7ad2bd64 100644 --- a/youcat/src/main/webapp/paths/tap-table-update.yaml +++ b/youcat/src/main/webapp/paths/tap-table-update.yaml @@ -2,7 +2,13 @@ get: summary: UWS 1.1 description: async job listing parameters: {} - responses: {} + responses: + 200: + $ref: ../components/uws-responses.yaml#/job-listing + 401: + $ref: ../components/std-responses.yaml#/not-authenticated + 403: + $ref: ../components/std-responses.yaml#/permission-denied post: summary: TAP table-update 1.2 description: TAP asynchronous table update (create UWS Job); can only specify one operation @@ -32,5 +38,9 @@ post: schema: type: boolean responses: - "303": - description: standard UWS redirect to the created job + 303: + $ref: ../components/uws-responses.yaml#/created + 401: + $ref: ../components/std-responses.yaml#/not-authenticated + 403: + $ref: ../components/std-responses.yaml#/permission-denied From 1cef3b90b20b2a1ade60880fe8cd112e4450afee Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Tue, 15 Oct 2024 12:21:45 -0700 Subject: [PATCH 06/23] tidy openapi for clarity --- youcat/src/main/webapp/openapi.yaml | 42 +++++++++++-------- youcat/src/main/webapp/paths/tap-async.yaml | 2 + youcat/src/main/webapp/paths/tap-load.yaml | 3 +- youcat/src/main/webapp/paths/tap-sync.yaml | 2 + .../main/webapp/paths/tap-table-update.yaml | 14 +++---- .../src/main/webapp/paths/uws-job-phase.yaml | 15 ++++++- youcat/src/main/webapp/paths/uws-job.yaml | 6 +++ .../main/webapp/paths/vosi-availability.yaml | 25 +---------- .../main/webapp/paths/vosi-capabilities.yaml | 2 + youcat/src/main/webapp/paths/vosi-table.yaml | 6 ++- .../src/main/webapp/paths/vosi-tableset.yaml | 1 + 11 files changed, 66 insertions(+), 52 deletions(-) diff --git a/youcat/src/main/webapp/openapi.yaml b/youcat/src/main/webapp/openapi.yaml index 6ab7ef6d..092bb582 100644 --- a/youcat/src/main/webapp/openapi.yaml +++ b/youcat/src/main/webapp/openapi.yaml @@ -1,10 +1,17 @@ openapi: 3.1.0 info: - title: user-managed TAP service (youcat) - version: "1.0" - description: This is more or less the current TAP-1.1 standard. + title: prototype TAP-1.2 with user managed tables + #version: "1.2" + description: | + This is more or less the current TAP-1.1 standard with some TAP-1.2 + extensions from the CADC/CANFAR youcat service servers: -- url: /youcat +- url: /tap + +## note: any of the $ref values below can be URLs to external (standard) OpenAPI +## components; examples below are commented out but would work if the resources +## were available at that location + paths: /sync: $ref: ./paths/tap-sync.yaml @@ -13,37 +20,38 @@ paths: $ref: ./paths/tap-async.yaml /async/{jobID}: $ref: ./paths/uws-job.yaml - #$ref: https://haproxy.cadc.dao.nrc.ca/site/vault/files/pdowler/openapi/uws-job.yaml + #$ref: https://example.net/std/openapi/uws-job.yaml /async/{jobID}/phase: $ref: ./paths/uws-job-phase.yaml - #$ref: https://haproxy.cadc.dao.nrc.ca/site/vault/files/pdowler/openapi/uws-job-phase.yaml - ## TODO: more resources under /async/{jobID}?? + #$ref: https://example.net/std/openapi/uws-job-phase.yaml + ## TODO: more resources under /async/{jobID}? /tables: $ref: ./paths/vosi-tableset.yaml - #$ref: https://haproxy.cadc.dao.nrc.ca/site/vault/files/pdowler/openapi/vosi-tableset.yaml + #$ref: https://example.net/std/openapi/vosi-tableset.yaml /tables/{name}: $ref: ./paths/vosi-table.yaml - #$ref: https://haproxy.cadc.dao.nrc.ca/site/vault/files/pdowler/openapi/vosi-table.yaml + #$ref: https://example.net/std/openapi/vosi-table.yaml /table-update: $ref: ./paths/tap-table-update.yaml /table-update/{jobID}: $ref: ./paths/uws-job.yaml - #$ref: https://haproxy.cadc.dao.nrc.ca/site/vault/files/pdowler/openapi/uws-job.yaml + #$ref: https://example.net/std/openapi/uws-job.yaml /table-update/{jobID}/phase: $ref: ./paths/uws-job-phase.yaml - #$ref: https://haproxy.cadc.dao.nrc.ca/site/vault/files/pdowler/openapi/uws-job-phase.yaml - ## TODO: more resources under /table-update/{jobID}?? - + #$ref: https://example.net/std/openapi/uws-job-phase.yaml + ## TODO: more resources under /async/{jobID}? + /load/{name}: $ref: ./paths/tap-load.yaml - - ## TODO: set permissions + ## TODO: youcat has a mechanism to set permissions on schemas and tables + ## that is embarassingly simple/limited/bad + /availability: $ref: ./paths/vosi-availability.yaml - #$ref: https://haproxy.cadc.dao.nrc.ca/site/vault/files/pdowler/openapi/vosi-availability.yaml + #$ref: https://example.net/std/openapi//vosi-availability.yaml /capabilities: $ref: ./paths/vosi-capabilities.yaml - #$ref: https://haproxy.cadc.dao.nrc.ca/site/vault/files/pdowler/openapi/vosi-capabilities.yaml + #$ref: https://example.net/std/openapi/vosi-capabilities.yaml diff --git a/youcat/src/main/webapp/paths/tap-async.yaml b/youcat/src/main/webapp/paths/tap-async.yaml index 4d94ff5c..4b2abb7f 100644 --- a/youcat/src/main/webapp/paths/tap-async.yaml +++ b/youcat/src/main/webapp/paths/tap-async.yaml @@ -1,4 +1,5 @@ get: + operationId: query-job-list summary: UWS 1.1 description: async job listing parameters: @@ -10,6 +11,7 @@ get: 403: $ref: ../components/std-responses.yaml#/permission-denied post: + operationId: query-job-create summary: TAP-async 1.1 description: TAP asynchronous query endpoint (create UWS Job) parameters: diff --git a/youcat/src/main/webapp/paths/tap-load.yaml b/youcat/src/main/webapp/paths/tap-load.yaml index 710fa86e..2d4bb3fe 100644 --- a/youcat/src/main/webapp/paths/tap-load.yaml +++ b/youcat/src/main/webapp/paths/tap-load.yaml @@ -1,4 +1,5 @@ post: + operationId: tap-bulk-load summary: bulk load or row data description: TAP synchronous bulk load endpoint parameters: @@ -36,4 +37,4 @@ components: name: VOTABLE namespace: http://www.ivoa.net/xml/VOTable/v1.3 - \ No newline at end of file + diff --git a/youcat/src/main/webapp/paths/tap-sync.yaml b/youcat/src/main/webapp/paths/tap-sync.yaml index ce077e2c..e3f4a944 100644 --- a/youcat/src/main/webapp/paths/tap-sync.yaml +++ b/youcat/src/main/webapp/paths/tap-sync.yaml @@ -1,4 +1,5 @@ get: + operationId: sync-query-job-get summary: TAP-sync 1.1 description: TAP synchronous query endpoint parameters: @@ -20,6 +21,7 @@ get: 403: $ref: ../components/std-responses.yaml#/permission-denied post: + operationId: sync-query-job-create summary: TAP-sync 1.1 description: TAP synchronous query endpoint parameters: diff --git a/youcat/src/main/webapp/paths/tap-table-update.yaml b/youcat/src/main/webapp/paths/tap-table-update.yaml index 7ad2bd64..78b37280 100644 --- a/youcat/src/main/webapp/paths/tap-table-update.yaml +++ b/youcat/src/main/webapp/paths/tap-table-update.yaml @@ -1,7 +1,8 @@ get: + operationId: table-update-job-list summary: UWS 1.1 description: async job listing - parameters: {} + parameters: responses: 200: $ref: ../components/uws-responses.yaml#/job-listing @@ -10,7 +11,8 @@ get: 403: $ref: ../components/std-responses.yaml#/permission-denied post: - summary: TAP table-update 1.2 + operationId: table-update-job-create + summary: proto - TAP table-update 1.2 description: TAP asynchronous table update (create UWS Job); can only specify one operation parameters: - name: TABLE @@ -31,15 +33,9 @@ post: required: false schema: type: boolean - - name: INGEST - in: query - description: ingest operation; ingest an existing database table into tap_schema - required: false - schema: - type: boolean responses: 303: - $ref: ../components/uws-responses.yaml#/created + description: standard UWS redirect to the created job 401: $ref: ../components/std-responses.yaml#/not-authenticated 403: diff --git a/youcat/src/main/webapp/paths/uws-job-phase.yaml b/youcat/src/main/webapp/paths/uws-job-phase.yaml index d60be73c..85d56da0 100644 --- a/youcat/src/main/webapp/paths/uws-job-phase.yaml +++ b/youcat/src/main/webapp/paths/uws-job-phase.yaml @@ -1,13 +1,26 @@ get: + operationId: job-phase-get summary: UWS 1.1 description: job phase resource + parameters: + - name: jobID + in: path + description: unique job identifier generated by the server + required: true + type: string responses: 200: description: successful response post: + operationId: job-phase-update summary: UWS 1.1 description: update job parameters: + - name: jobID + in: path + description: unique job identifier generated by the server + required: true + type: string - name: PHASE in: query description: attempt to change the phase @@ -25,4 +38,4 @@ post: 403: $ref: ../components/std-responses.yaml#/permission-denied 404: - $ref: ../components/std-responses.yaml#/not-found \ No newline at end of file + $ref: ../components/std-responses.yaml#/not-found diff --git a/youcat/src/main/webapp/paths/uws-job.yaml b/youcat/src/main/webapp/paths/uws-job.yaml index 4ae7db5a..ada60921 100644 --- a/youcat/src/main/webapp/paths/uws-job.yaml +++ b/youcat/src/main/webapp/paths/uws-job.yaml @@ -1,7 +1,13 @@ get: + operationId: job-get summary: UWS 1.1 description: job resource parameters: + - name: jobID + in: path + description: unique job identifier generated by the server + required: true + type: string - name: WAIT in: query description: wait for the specified time in seconds or until the phase changes diff --git a/youcat/src/main/webapp/paths/vosi-availability.yaml b/youcat/src/main/webapp/paths/vosi-availability.yaml index ec17090e..6a96d1c4 100644 --- a/youcat/src/main/webapp/paths/vosi-availability.yaml +++ b/youcat/src/main/webapp/paths/vosi-availability.yaml @@ -1,4 +1,5 @@ head: + operationId: availability-heartbeat tag: VOSI summary: VOSI Availability heartbeat check description: | @@ -7,8 +8,8 @@ head: responses: 200: description: service is reachable - ## TBD: response code for read-only mode? off line mode? get: + operationId: availability-check tag: VOSI summary: VOSI Availability full check description: | @@ -23,28 +24,6 @@ get: text/xml: schema: $ref: '#/components/schemas/availability' -post: - tag: VOSI - summary: (CADC extension) modify the state (availability) of a running service - description: | - An operator can modify the state of a service instance to put it into one of - three modes: offline, read-only, and read-write (normal). The detailed meaning of - these modes depends on the nature of the service. - parameters: - - name: STATE - in: query - description: new service state - required: true - schema: - type: string - enum: [ReadWrite, ReadOnly, Offline] - responses: - 204: - description: service state updated - 401: - $ref: ../components/std-responses.yaml#/not-authenticated - 403: - $ref: ../components/std-responses.yaml#/permission-denied components: schemas: diff --git a/youcat/src/main/webapp/paths/vosi-capabilities.yaml b/youcat/src/main/webapp/paths/vosi-capabilities.yaml index 0c4033be..38751e42 100644 --- a/youcat/src/main/webapp/paths/vosi-capabilities.yaml +++ b/youcat/src/main/webapp/paths/vosi-capabilities.yaml @@ -1,4 +1,5 @@ head: + operationId: capabilities-probe tag: VOSI summary: VOSI Capabilities description: | @@ -16,6 +17,7 @@ head: 403: description: authentication succeed, caller is not permitted to make requests get: + operationId: capabilities-get tag: VOSI summary: VOSI Capabilities description: Get the set of VOResource capability descriptions for this service. diff --git a/youcat/src/main/webapp/paths/vosi-table.yaml b/youcat/src/main/webapp/paths/vosi-table.yaml index 0fdb2f19..62bcda86 100644 --- a/youcat/src/main/webapp/paths/vosi-table.yaml +++ b/youcat/src/main/webapp/paths/vosi-table.yaml @@ -1,4 +1,5 @@ get: + operationId: vosi-table-get summary: get metadata for the specified table description: provides the table metadata for a single schema or table parameters: @@ -19,6 +20,7 @@ get: 404: $ref: ../components/std-responses.yaml#/not-found post: + operationId: vosi-table-update summary: proto - update table metadata description: | update the tap_schema metadata from description; @@ -46,6 +48,7 @@ post: 404: $ref: ../components/std-responses.yaml#/not-found put: + operationId: vosi-table-create summary: proto - create table description: create table from description parameters: @@ -71,6 +74,7 @@ put: 404: $ref: ../components/std-responses.yaml#/not-found delete: + operationId: vosi-table-delete summary: proto - delete table parameters: - name: name @@ -106,4 +110,4 @@ components: # type: object # xml: # name: VOTABLE -# namespace: http://www.ivoa.net/xml/VOTable/v1.3 \ No newline at end of file +# namespace: http://www.ivoa.net/xml/VOTable/v1.3 diff --git a/youcat/src/main/webapp/paths/vosi-tableset.yaml b/youcat/src/main/webapp/paths/vosi-tableset.yaml index 8c4218de..fb0b5646 100644 --- a/youcat/src/main/webapp/paths/vosi-tableset.yaml +++ b/youcat/src/main/webapp/paths/vosi-tableset.yaml @@ -1,4 +1,5 @@ get: + operationId: vosi-tableset-get tag: VOSI tag: table metadata summary: VOSI Tables From c7582e8103939854e6c666f548124589a4b9c5b3 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Fri, 9 May 2025 14:13:34 -0700 Subject: [PATCH 07/23] openapi updates for youcat this now depends on component files puleld from ivoa-std repos (hack) --- .../components/parameters/dali-maxrec.yaml | 6 - .../parameters/dali-responseformat.yaml | 5 - .../components/parameters/tap-format.yaml | 5 - .../components/parameters/tap-lang.yaml | 6 - .../components/parameters/tap-params.yaml | 39 ------ .../components/parameters/tap-query.yaml | 6 - .../components/parameters/tap-upload.yaml | 5 - .../main/webapp/components/std-responses.yaml | 19 --- .../main/webapp/components/tap-responses.yaml | 7 -- .../main/webapp/components/uws-responses.yaml | 36 ------ youcat/src/main/webapp/openapi.yaml | 59 ++++----- youcat/src/main/webapp/paths/tap-async.yaml | 30 ----- youcat/src/main/webapp/paths/tap-load.yaml | 40 ------- youcat/src/main/webapp/paths/tap-sync.yaml | 45 ------- .../main/webapp/paths/tap-table-update.yaml | 42 ------- .../src/main/webapp/paths/uws-job-phase.yaml | 41 ------- youcat/src/main/webapp/paths/uws-job.yaml | 25 ---- .../main/webapp/paths/vosi-availability.yaml | 38 ------ .../main/webapp/paths/vosi-capabilities.yaml | 45 ------- youcat/src/main/webapp/paths/vosi-table.yaml | 113 ------------------ .../src/main/webapp/paths/vosi-tableset.yaml | 34 ------ 21 files changed, 22 insertions(+), 624 deletions(-) delete mode 100644 youcat/src/main/webapp/components/parameters/dali-maxrec.yaml delete mode 100644 youcat/src/main/webapp/components/parameters/dali-responseformat.yaml delete mode 100644 youcat/src/main/webapp/components/parameters/tap-format.yaml delete mode 100644 youcat/src/main/webapp/components/parameters/tap-lang.yaml delete mode 100644 youcat/src/main/webapp/components/parameters/tap-params.yaml delete mode 100644 youcat/src/main/webapp/components/parameters/tap-query.yaml delete mode 100644 youcat/src/main/webapp/components/parameters/tap-upload.yaml delete mode 100644 youcat/src/main/webapp/components/std-responses.yaml delete mode 100644 youcat/src/main/webapp/components/tap-responses.yaml delete mode 100644 youcat/src/main/webapp/components/uws-responses.yaml delete mode 100644 youcat/src/main/webapp/paths/tap-async.yaml delete mode 100644 youcat/src/main/webapp/paths/tap-load.yaml delete mode 100644 youcat/src/main/webapp/paths/tap-sync.yaml delete mode 100644 youcat/src/main/webapp/paths/tap-table-update.yaml delete mode 100644 youcat/src/main/webapp/paths/uws-job-phase.yaml delete mode 100644 youcat/src/main/webapp/paths/uws-job.yaml delete mode 100644 youcat/src/main/webapp/paths/vosi-availability.yaml delete mode 100644 youcat/src/main/webapp/paths/vosi-capabilities.yaml delete mode 100644 youcat/src/main/webapp/paths/vosi-table.yaml delete mode 100644 youcat/src/main/webapp/paths/vosi-tableset.yaml diff --git a/youcat/src/main/webapp/components/parameters/dali-maxrec.yaml b/youcat/src/main/webapp/components/parameters/dali-maxrec.yaml deleted file mode 100644 index 9260433f..00000000 --- a/youcat/src/main/webapp/components/parameters/dali-maxrec.yaml +++ /dev/null @@ -1,6 +0,0 @@ -name: MAXREC -in: query -description: request a specific limit on number of rows to return -schema: - type: integer - format: int64 diff --git a/youcat/src/main/webapp/components/parameters/dali-responseformat.yaml b/youcat/src/main/webapp/components/parameters/dali-responseformat.yaml deleted file mode 100644 index 202eee4c..00000000 --- a/youcat/src/main/webapp/components/parameters/dali-responseformat.yaml +++ /dev/null @@ -1,5 +0,0 @@ -name: RESPONSEFORMAT -in: query -description: select output table format -schema: - type: string diff --git a/youcat/src/main/webapp/components/parameters/tap-format.yaml b/youcat/src/main/webapp/components/parameters/tap-format.yaml deleted file mode 100644 index 40c253bf..00000000 --- a/youcat/src/main/webapp/components/parameters/tap-format.yaml +++ /dev/null @@ -1,5 +0,0 @@ -name: FORMAT -in: query -description: "supported for backwards compatibility to 1.0 (see: RESPONSEFORMAT)" -schema: - type: string diff --git a/youcat/src/main/webapp/components/parameters/tap-lang.yaml b/youcat/src/main/webapp/components/parameters/tap-lang.yaml deleted file mode 100644 index c432ae71..00000000 --- a/youcat/src/main/webapp/components/parameters/tap-lang.yaml +++ /dev/null @@ -1,6 +0,0 @@ -name: LANG -in: query -description: specify the query language used in the QUERY parameter -required: true -schema: - type: string diff --git a/youcat/src/main/webapp/components/parameters/tap-params.yaml b/youcat/src/main/webapp/components/parameters/tap-params.yaml deleted file mode 100644 index 6ab3791c..00000000 --- a/youcat/src/main/webapp/components/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 diff --git a/youcat/src/main/webapp/components/parameters/tap-query.yaml b/youcat/src/main/webapp/components/parameters/tap-query.yaml deleted file mode 100644 index 92e9c204..00000000 --- a/youcat/src/main/webapp/components/parameters/tap-query.yaml +++ /dev/null @@ -1,6 +0,0 @@ -name: QUERY -in: query -description: specify the query -required: true -schema: - type: string diff --git a/youcat/src/main/webapp/components/parameters/tap-upload.yaml b/youcat/src/main/webapp/components/parameters/tap-upload.yaml deleted file mode 100644 index 27302d60..00000000 --- a/youcat/src/main/webapp/components/parameters/tap-upload.yaml +++ /dev/null @@ -1,5 +0,0 @@ -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/youcat/src/main/webapp/components/std-responses.yaml b/youcat/src/main/webapp/components/std-responses.yaml deleted file mode 100644 index 3538f635..00000000 --- a/youcat/src/main/webapp/components/std-responses.yaml +++ /dev/null @@ -1,19 +0,0 @@ -# UWS create job response -not-authenticated: - description: authentication is required and current attempt failed - headers: - www-authenticate: - schema: - type: string -permission-denied: - description: caller not allowed to perform operation - content: - text/plain: - schema: - type: string -not-found: - description: resource not found - content: - text/plain: - schema: - type: string diff --git a/youcat/src/main/webapp/components/tap-responses.yaml b/youcat/src/main/webapp/components/tap-responses.yaml deleted file mode 100644 index cc11415d..00000000 --- a/youcat/src/main/webapp/components/tap-responses.yaml +++ /dev/null @@ -1,7 +0,0 @@ -# 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/youcat/src/main/webapp/components/uws-responses.yaml b/youcat/src/main/webapp/components/uws-responses.yaml deleted file mode 100644 index 632d433f..00000000 --- a/youcat/src/main/webapp/components/uws-responses.yaml +++ /dev/null @@ -1,36 +0,0 @@ -# UWS create job response -created: - description: standard UWS 1.1 redirect to the created job URL - headers: - location: - schema: - type: string - format: uri -invalid-phase-change: - description: the requested phase change is invalid - content: - text/plain: - schema: - type: string -job-listing: - description: list of jobs owned by the caller - content: - text/xml: - schema: - type: object - xml: - name: jobs - prefix: uws - namespace: http://www.ivoa.net/xml/UWS/v1.0 - -components: - schemas: - jobDoc: - content: - text/xml: - schema: - type: object - xml: - name: job - prefix: uws - namespace: http://www.ivoa.net/xml/UWS/v1.0 diff --git a/youcat/src/main/webapp/openapi.yaml b/youcat/src/main/webapp/openapi.yaml index 092bb582..f9bedcb0 100644 --- a/youcat/src/main/webapp/openapi.yaml +++ b/youcat/src/main/webapp/openapi.yaml @@ -6,52 +6,37 @@ info: This is more or less the current TAP-1.1 standard with some TAP-1.2 extensions from the CADC/CANFAR youcat service servers: -- url: /tap +- url: /youcat -## note: any of the $ref values below can be URLs to external (standard) OpenAPI -## components; examples below are commented out but would work if the resources -## were available at that location +## note: +## any of the $ref values below can be URLs to external (standard) OpenAPI components paths: - /sync: - $ref: ./paths/tap-sync.yaml + /capabilities: + $ref: ./openapi/vosi/vosi-capabilities.yaml + + /tables: + $ref: ./openapi/vosi/vosi-tableset.yaml + /tables/{name}: + $ref: ./openapi/vosi/vosi-table.yaml + /sync: + $ref: ./openapi/tap/tap-sync.yaml /async: - $ref: ./paths/tap-async.yaml + $ref: ./openapi/tap/tap-async.yaml /async/{jobID}: - $ref: ./paths/uws-job.yaml - #$ref: https://example.net/std/openapi/uws-job.yaml + $ref: ./openapi/uws/uws-job.yaml /async/{jobID}/phase: - $ref: ./paths/uws-job-phase.yaml - #$ref: https://example.net/std/openapi/uws-job-phase.yaml - ## TODO: more resources under /async/{jobID}? - - /tables: - $ref: ./paths/vosi-tableset.yaml - #$ref: https://example.net/std/openapi/vosi-tableset.yaml - /tables/{name}: - $ref: ./paths/vosi-table.yaml - #$ref: https://example.net/std/openapi/vosi-table.yaml + $ref: ./openapi/uws/uws-job-phase.yaml /table-update: - $ref: ./paths/tap-table-update.yaml + $ref: ./openapi/tap/tap-table-update.yaml /table-update/{jobID}: - $ref: ./paths/uws-job.yaml - #$ref: https://example.net/std/openapi/uws-job.yaml + $ref: ./openapi/uws/uws-job.yaml /table-update/{jobID}/phase: - $ref: ./paths/uws-job-phase.yaml - #$ref: https://example.net/std/openapi/uws-job-phase.yaml - ## TODO: more resources under /async/{jobID}? + $ref: ./openapi/uws/uws-job-phase.yaml - /load/{name}: - $ref: ./paths/tap-load.yaml - - ## TODO: youcat has a mechanism to set permissions on schemas and tables - ## that is embarassingly simple/limited/bad - - /availability: - $ref: ./paths/vosi-availability.yaml - #$ref: https://example.net/std/openapi//vosi-availability.yaml - /capabilities: - $ref: ./paths/vosi-capabilities.yaml - #$ref: https://example.net/std/openapi/vosi-capabilities.yaml +## TBD +# /load/{name}: +# $ref: ./openapi/tap/tap-load.yaml +# /permissions/{name}: diff --git a/youcat/src/main/webapp/paths/tap-async.yaml b/youcat/src/main/webapp/paths/tap-async.yaml deleted file mode 100644 index 4b2abb7f..00000000 --- a/youcat/src/main/webapp/paths/tap-async.yaml +++ /dev/null @@ -1,30 +0,0 @@ -get: - operationId: query-job-list - summary: UWS 1.1 - description: async job listing - parameters: - responses: - 200: - $ref: ../components/uws-responses.yaml#/job-listing - 401: - $ref: ../components/std-responses.yaml#/not-authenticated - 403: - $ref: ../components/std-responses.yaml#/permission-denied -post: - operationId: query-job-create - summary: TAP-async 1.1 - description: TAP asynchronous query endpoint (create UWS Job) - parameters: - - $ref: ../components/parameters/tap-lang.yaml - - $ref: ../components/parameters/tap-query.yaml - - $ref: ../components/parameters/tap-upload.yaml - - $ref: ../components/parameters/tap-format.yaml - - $ref: ../components/parameters/dali-maxrec.yaml - - $ref: ../components/parameters/dali-responseformat.yaml - responses: - 303: - $ref: ../components/uws-responses.yaml#/created - 401: - $ref: ../components/std-responses.yaml#/not-authenticated - 403: - $ref: ../components/std-responses.yaml#/permission-denied diff --git a/youcat/src/main/webapp/paths/tap-load.yaml b/youcat/src/main/webapp/paths/tap-load.yaml deleted file mode 100644 index 2d4bb3fe..00000000 --- a/youcat/src/main/webapp/paths/tap-load.yaml +++ /dev/null @@ -1,40 +0,0 @@ -post: - operationId: tap-bulk-load - 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 - - diff --git a/youcat/src/main/webapp/paths/tap-sync.yaml b/youcat/src/main/webapp/paths/tap-sync.yaml deleted file mode 100644 index e3f4a944..00000000 --- a/youcat/src/main/webapp/paths/tap-sync.yaml +++ /dev/null @@ -1,45 +0,0 @@ -get: - operationId: sync-query-job-get - summary: TAP-sync 1.1 - description: TAP synchronous query endpoint - parameters: - - $ref: ../components/parameters/tap-lang.yaml - - $ref: ../components/parameters/tap-query.yaml - - $ref: ../components/parameters/tap-upload.yaml - - $ref: ../components/parameters/tap-format.yaml - - $ref: ../components/parameters/dali-maxrec.yaml - - $ref: ../components/parameters/dali-responseformat.yaml - responses: - 200: - description: successful response - 303: - description: redirect to the job result (optional) - 400: - $ref: ../components/tap-responses.yaml#/invalid-query - 401: - $ref: ../components/std-responses.yaml#/not-authenticated - 403: - $ref: ../components/std-responses.yaml#/permission-denied -post: - operationId: sync-query-job-create - summary: TAP-sync 1.1 - description: TAP synchronous query endpoint - parameters: - - $ref: ../components/parameters/tap-lang.yaml - - $ref: ../components/parameters/tap-query.yaml - - $ref: ../components/parameters/tap-upload.yaml - - $ref: ../components/parameters/tap-format.yaml - - $ref: ../components/parameters/dali-maxrec.yaml - - $ref: ../components/parameters/dali-responseformat.yaml - responses: - 200: - description: successful response - 303: - description: redirect to the job result (optional) - 400: - $ref: ../components/tap-responses.yaml#/invalid-query - 401: - $ref: ../components/std-responses.yaml#/not-authenticated - 403: - $ref: ../components/std-responses.yaml#/permission-denied - diff --git a/youcat/src/main/webapp/paths/tap-table-update.yaml b/youcat/src/main/webapp/paths/tap-table-update.yaml deleted file mode 100644 index 78b37280..00000000 --- a/youcat/src/main/webapp/paths/tap-table-update.yaml +++ /dev/null @@ -1,42 +0,0 @@ -get: - operationId: table-update-job-list - summary: UWS 1.1 - description: async job listing - parameters: - responses: - 200: - $ref: ../components/uws-responses.yaml#/job-listing - 401: - $ref: ../components/std-responses.yaml#/not-authenticated - 403: - $ref: ../components/std-responses.yaml#/permission-denied -post: - operationId: table-update-job-create - summary: proto - TAP table-update 1.2 - description: TAP asynchronous table update (create UWS Job); can only specify one operation - parameters: - - name: TABLE - in: query - description: a single table name as provided in tap_schema - required: true - schema: - type: string - - name: INDEX - in: query - description: create index operation; value is a column name in the table - required: false - schema: - type: string - - name: UNIQUE - in: query - description: qualifier for INDEX to create a unique index - required: false - schema: - type: boolean - responses: - 303: - description: standard UWS redirect to the created job - 401: - $ref: ../components/std-responses.yaml#/not-authenticated - 403: - $ref: ../components/std-responses.yaml#/permission-denied diff --git a/youcat/src/main/webapp/paths/uws-job-phase.yaml b/youcat/src/main/webapp/paths/uws-job-phase.yaml deleted file mode 100644 index 85d56da0..00000000 --- a/youcat/src/main/webapp/paths/uws-job-phase.yaml +++ /dev/null @@ -1,41 +0,0 @@ -get: - operationId: job-phase-get - summary: UWS 1.1 - description: job phase resource - parameters: - - name: jobID - in: path - description: unique job identifier generated by the server - required: true - type: string - responses: - 200: - description: successful response -post: - operationId: job-phase-update - summary: UWS 1.1 - description: update job - parameters: - - name: jobID - in: path - description: unique job identifier generated by the server - required: true - type: string - - name: PHASE - in: query - description: attempt to change the phase - required: true - schema: - type: string - enum: [ABORT, RUN] - responses: - 200: - description: phase change successful - 400: - $ref: ../components/uws-responses.yaml#/invalid-phase-change - 401: - $ref: ../components/std-responses.yaml#/not-authenticated - 403: - $ref: ../components/std-responses.yaml#/permission-denied - 404: - $ref: ../components/std-responses.yaml#/not-found diff --git a/youcat/src/main/webapp/paths/uws-job.yaml b/youcat/src/main/webapp/paths/uws-job.yaml deleted file mode 100644 index ada60921..00000000 --- a/youcat/src/main/webapp/paths/uws-job.yaml +++ /dev/null @@ -1,25 +0,0 @@ -get: - operationId: job-get - summary: UWS 1.1 - description: job resource - parameters: - - name: jobID - in: path - description: unique job identifier generated by the server - required: true - type: string - - name: WAIT - in: query - description: wait for the specified time in seconds or until the phase changes - required: false - type: integer - responses: - 200: - description: successful response - $ref: '../components/uws-responses.yaml#/components/schemas/jobDoc' - 401: - $ref: ../components/std-responses.yaml#/not-authenticated - 403: - $ref: ../components/std-responses.yaml#/permission-denied - 404: - $ref: ../components/std-responses.yaml#/not-found diff --git a/youcat/src/main/webapp/paths/vosi-availability.yaml b/youcat/src/main/webapp/paths/vosi-availability.yaml deleted file mode 100644 index 6a96d1c4..00000000 --- a/youcat/src/main/webapp/paths/vosi-availability.yaml +++ /dev/null @@ -1,38 +0,0 @@ -head: - operationId: availability-heartbeat - tag: VOSI - summary: VOSI Availability heartbeat check - description: | - Perform a minimal check that the service is reachable and running. This - check is intended to be very fast and lightweight. - responses: - 200: - description: service is reachable -get: - operationId: availability-check - tag: VOSI - summary: VOSI Availability full check - description: | - Perform a complete check that the service is operational. This normally - includes checking the availability of back end resources (e.g. database, - storage, ...) and that other services that this service depends on (e.g. AAI - services) are reachable (via heartbeat availability check). - responses: - 200: - description: A VOSI availability document in XML. - content: - text/xml: - schema: - $ref: '#/components/schemas/availability' - -components: - schemas: - availability: - content: - text/xml: - schema: - type: object - xml: - name: availability - prefix: vosi - namespace: http://www.ivoa.net/xml/VOSIAvailability/v1.0 diff --git a/youcat/src/main/webapp/paths/vosi-capabilities.yaml b/youcat/src/main/webapp/paths/vosi-capabilities.yaml deleted file mode 100644 index 38751e42..00000000 --- a/youcat/src/main/webapp/paths/vosi-capabilities.yaml +++ /dev/null @@ -1,45 +0,0 @@ -head: - operationId: capabilities-probe - tag: VOSI - summary: VOSI Capabilities - description: | - Get standard headers for the service. The standard headers should include - AAI related headers (www-authenticate challenges or x-vo-authenticated - indicator) if applicable, server name and version info, and other - applicable header information. SSO-next: clients use this operation to probe - for available authentiction methods. - responses: - 200: - description: successful probe, service allows request from caller - 401: - description: | - successful probe, service requires authentication or attempted authentication failed - 403: - description: authentication succeed, caller is not permitted to make requests -get: - operationId: capabilities-get - tag: VOSI - summary: VOSI Capabilities - description: Get the set of VOResource capability descriptions for this service. - responses: - 200: - description: A VOSI Capabilities document in XML. - content: - text/xml: - schema: - $ref: '#/components/schemas/capabilities' - 401: - $ref: ../components/std-responses.yaml#/not-authenticated - 403: - $ref: ../components/std-responses.yaml#/permission-denied -components: - schemas: - capabilities: - content: - text/xml: - schema: - type: object - xml: - name: capabilities - prefix: vosi - namespace: http://www.ivoa.net/xml/VOSICapabilities/v1.0 diff --git a/youcat/src/main/webapp/paths/vosi-table.yaml b/youcat/src/main/webapp/paths/vosi-table.yaml deleted file mode 100644 index 62bcda86..00000000 --- a/youcat/src/main/webapp/paths/vosi-table.yaml +++ /dev/null @@ -1,113 +0,0 @@ -get: - operationId: vosi-table-get - summary: get metadata for the specified table - description: provides the table metadata for a single schema or table - parameters: - - name: name - in: path - description: a single schema name or table name as provided in tap_schema - required: true - schema: - type: string - responses: - 200: - description: metadata for the specified table - $ref: '#/components/schemas/tableDoc' - 401: - $ref: ../components/std-responses.yaml#/not-authenticated - 403: - $ref: ../components/std-responses.yaml#/permission-denied - 404: - $ref: ../components/std-responses.yaml#/not-found -post: - operationId: vosi-table-update - summary: proto - update table metadata - description: | - update the tap_schema metadata from description; - TBD: what can be changed and what is immutable? - parameters: - - name: name - in: path - description: the fully qualified name of the table to create - required: true - schema: - type: string - requestBody: - $ref: '#/components/schemas/tableDoc' - responses: - 204: - description: table updated - 400: - description: update table metadata failed due to invalid input - content: - text/plain: - 401: - $ref: ../components/std-responses.yaml#/not-authenticated - 403: - $ref: ../components/std-responses.yaml#/permission-denied - 404: - $ref: ../components/std-responses.yaml#/not-found -put: - operationId: vosi-table-create - summary: proto - create table - description: create table from description - parameters: - - name: name - in: path - description: the fully qualified name of the table to create - required: true - schema: - type: string - requestBody: - $ref: '#/components/schemas/tableDoc' - responses: - 201: - description: table created - 400: - description: create table failed due to invalid input - content: - text/plain: - 401: - $ref: ../components/std-responses.yaml#/not-authenticated - 403: - $ref: ../components/std-responses.yaml#/permission-denied - 404: - $ref: ../components/std-responses.yaml#/not-found -delete: - operationId: vosi-table-delete - summary: proto - delete table - parameters: - - name: name - in: path - description: | - the table to delete; - TBD: remove from tap_schema and drop from db? - required: true - schema: - type: string - responses: - 204: - description: table dropped - 401: - $ref: ../components/std-responses.yaml#/not-authenticated - 403: - $ref: ../components/std-responses.yaml#/permission-denied - 404: - $ref: ../components/std-responses.yaml#/not-found -components: - schemas: - tableDoc: - content: - text/xml: - schema: - type: object - xml: - name: table - prefix: vosi - namespace: http://www.ivoa.net/xml/VOSITables/v1.0 -# application/x-votable+xml: -# schema: -# type: object -# xml: -# name: VOTABLE -# namespace: http://www.ivoa.net/xml/VOTable/v1.3 diff --git a/youcat/src/main/webapp/paths/vosi-tableset.yaml b/youcat/src/main/webapp/paths/vosi-tableset.yaml deleted file mode 100644 index fb0b5646..00000000 --- a/youcat/src/main/webapp/paths/vosi-tableset.yaml +++ /dev/null @@ -1,34 +0,0 @@ -get: - operationId: vosi-tableset-get - tag: VOSI - tag: table metadata - summary: VOSI Tables - description: Provides the table metadata in the form of a TableSet description - parameters: - - name: DETAIL - in: query - description: level of detail requested - required: false - schema: - type: string - enum: [min, max] - responses: - 200: - description: metadata for schemas and tables - $ref: '#/components/schemas/tablesetDoc' - 401: - $ref: ../components/std-responses.yaml#/not-authenticated - 403: - $ref: ../components/std-responses.yaml#/permission-denied -components: - schemas: - tablesetDoc: - content: - text/xml: - schema: - type: object - xml: - name: tableset - prefix: vosi - namespace: http://www.ivoa.net/xml/VOSITables/v1.0 - From b71c51c1bdf49ed05792b30c4045a4d0355011c0 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Thu, 15 May 2025 13:10:55 -0700 Subject: [PATCH 08/23] youcat rename in TAP/openapi.yaml --- youcat/src/main/webapp/openapi.yaml | 20 ++++++++------------ 1 file changed, 8 insertions(+), 12 deletions(-) diff --git a/youcat/src/main/webapp/openapi.yaml b/youcat/src/main/webapp/openapi.yaml index f9bedcb0..585a8bb4 100644 --- a/youcat/src/main/webapp/openapi.yaml +++ b/youcat/src/main/webapp/openapi.yaml @@ -3,23 +3,17 @@ info: title: prototype TAP-1.2 with user managed tables #version: "1.2" description: | - This is more or less the current TAP-1.1 standard with some TAP-1.2 - extensions from the CADC/CANFAR youcat service + This is the WD-TAP-1.2 API specification with components imported from + VOSI, UWS, and DALI. servers: - url: /youcat -## note: ## any of the $ref values below can be URLs to external (standard) OpenAPI components paths: /capabilities: $ref: ./openapi/vosi/vosi-capabilities.yaml - /tables: - $ref: ./openapi/vosi/vosi-tableset.yaml - /tables/{name}: - $ref: ./openapi/vosi/vosi-table.yaml - /sync: $ref: ./openapi/tap/tap-sync.yaml /async: @@ -29,6 +23,12 @@ paths: /async/{jobID}/phase: $ref: ./openapi/uws/uws-job-phase.yaml + /tables: + $ref: ./openapi/vosi/vosi-tableset.yaml + /tables/{name}: + $ref: ./openapi/vosi/vosi-table.yaml + +# uncertain if table-update is vosi or tap or ??? /table-update: $ref: ./openapi/tap/tap-table-update.yaml /table-update/{jobID}: @@ -36,7 +36,3 @@ paths: /table-update/{jobID}/phase: $ref: ./openapi/uws/uws-job-phase.yaml -## TBD -# /load/{name}: -# $ref: ./openapi/tap/tap-load.yaml -# /permissions/{name}: From 6952d38bd4ce9898ef9d293f2500208e41f0e0f3 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Fri, 16 May 2025 12:40:28 -0700 Subject: [PATCH 09/23] update OpenAPI specs by pulling in components from ivoa-std repos --- youcat/src/main/webapp/openapi.yaml | 8 -- .../main/webapp/openapi/dali/dali-maxrec.yaml | 6 + .../openapi/dali/dali-responseformat.yaml | 5 + .../main/webapp/openapi/dali/dali-upload.yaml | 7 + .../main/webapp/openapi/tap/tap-async.yaml | 34 +++++ .../main/webapp/openapi/tap/tap-format.yaml | 5 + .../src/main/webapp/openapi/tap/tap-lang.yaml | 6 + .../src/main/webapp/openapi/tap/tap-load.yaml | 44 ++++++ .../main/webapp/openapi/tap/tap-query.yaml | 6 + .../webapp/openapi/tap/tap-responses.yaml | 7 + .../src/main/webapp/openapi/tap/tap-sync.yaml | 49 +++++++ .../webapp/openapi/uws/uws-job-phase.yaml | 46 +++++++ .../src/main/webapp/openapi/uws/uws-job.yaml | 26 ++++ .../webapp/openapi/uws/uws-responses.yaml | 37 +++++ .../openapi/vosi/vosi-capabilities.yaml | 47 +++++++ .../openapi/vosi/vosi-std-responses.yaml | 49 +++++++ .../main/webapp/openapi/vosi/vosi-table.yaml | 128 ++++++++++++++++++ .../webapp/openapi/vosi/vosi-tableset.yaml | 37 +++++ 18 files changed, 539 insertions(+), 8 deletions(-) create mode 100644 youcat/src/main/webapp/openapi/dali/dali-maxrec.yaml create mode 100644 youcat/src/main/webapp/openapi/dali/dali-responseformat.yaml create mode 100644 youcat/src/main/webapp/openapi/dali/dali-upload.yaml create mode 100644 youcat/src/main/webapp/openapi/tap/tap-async.yaml create mode 100644 youcat/src/main/webapp/openapi/tap/tap-format.yaml create mode 100644 youcat/src/main/webapp/openapi/tap/tap-lang.yaml create mode 100644 youcat/src/main/webapp/openapi/tap/tap-load.yaml create mode 100644 youcat/src/main/webapp/openapi/tap/tap-query.yaml create mode 100644 youcat/src/main/webapp/openapi/tap/tap-responses.yaml create mode 100644 youcat/src/main/webapp/openapi/tap/tap-sync.yaml create mode 100644 youcat/src/main/webapp/openapi/uws/uws-job-phase.yaml create mode 100644 youcat/src/main/webapp/openapi/uws/uws-job.yaml create mode 100644 youcat/src/main/webapp/openapi/uws/uws-responses.yaml create mode 100644 youcat/src/main/webapp/openapi/vosi/vosi-capabilities.yaml create mode 100644 youcat/src/main/webapp/openapi/vosi/vosi-std-responses.yaml create mode 100644 youcat/src/main/webapp/openapi/vosi/vosi-table.yaml create mode 100644 youcat/src/main/webapp/openapi/vosi/vosi-tableset.yaml diff --git a/youcat/src/main/webapp/openapi.yaml b/youcat/src/main/webapp/openapi.yaml index 585a8bb4..3eef898c 100644 --- a/youcat/src/main/webapp/openapi.yaml +++ b/youcat/src/main/webapp/openapi.yaml @@ -28,11 +28,3 @@ paths: /tables/{name}: $ref: ./openapi/vosi/vosi-table.yaml -# uncertain if table-update is vosi or tap or ??? - /table-update: - $ref: ./openapi/tap/tap-table-update.yaml - /table-update/{jobID}: - $ref: ./openapi/uws/uws-job.yaml - /table-update/{jobID}/phase: - $ref: ./openapi/uws/uws-job-phase.yaml - diff --git a/youcat/src/main/webapp/openapi/dali/dali-maxrec.yaml b/youcat/src/main/webapp/openapi/dali/dali-maxrec.yaml new file mode 100644 index 00000000..9260433f --- /dev/null +++ b/youcat/src/main/webapp/openapi/dali/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/youcat/src/main/webapp/openapi/dali/dali-responseformat.yaml b/youcat/src/main/webapp/openapi/dali/dali-responseformat.yaml new file mode 100644 index 00000000..202eee4c --- /dev/null +++ b/youcat/src/main/webapp/openapi/dali/dali-responseformat.yaml @@ -0,0 +1,5 @@ +name: RESPONSEFORMAT +in: query +description: select output table format +schema: + type: string diff --git a/youcat/src/main/webapp/openapi/dali/dali-upload.yaml b/youcat/src/main/webapp/openapi/dali/dali-upload.yaml new file mode 100644 index 00000000..415518b8 --- /dev/null +++ b/youcat/src/main/webapp/openapi/dali/dali-upload.yaml @@ -0,0 +1,7 @@ +name: UPLOAD +in: query +description: | + specify comma-separated name,location pair for a temporary table to be + uploaded and used in the request +schema: + type: string diff --git a/youcat/src/main/webapp/openapi/tap/tap-async.yaml b/youcat/src/main/webapp/openapi/tap/tap-async.yaml new file mode 100644 index 00000000..7659c9e4 --- /dev/null +++ b/youcat/src/main/webapp/openapi/tap/tap-async.yaml @@ -0,0 +1,34 @@ +get: + operationId: query-job-list + tags: + - TAP Query + summary: list async queries + description: TAP asynchronous query endpoint (list UWS Jobs) + parameters: + responses: + 200: + $ref: ../uws/uws-responses.yaml#/job-listing + 401: + $ref: ../vosi/vosi-std-responses.yaml#/not-authenticated + 403: + $ref: ../vosi/vosi-std-responses.yaml#/permission-denied +post: + operationId: query-job-create + tags: + - TAP Query + summary: create async query + description: TAP asynchronous query endpoint (create UWS Job) + parameters: + - $ref: ./tap-lang.yaml + - $ref: ./tap-query.yaml + - $ref: ./tap-format.yaml + - $ref: ../dali/dali-maxrec.yaml + - $ref: ../dali/dali-responseformat.yaml + - $ref: ../dali/dali-upload.yaml + responses: + 303: + $ref: ../uws/uws-responses.yaml#/created + 401: + $ref: ../vosi/vosi-std-responses.yaml#/not-authenticated + 403: + $ref: ../vosi/vosi-std-responses.yaml#/permission-denied diff --git a/youcat/src/main/webapp/openapi/tap/tap-format.yaml b/youcat/src/main/webapp/openapi/tap/tap-format.yaml new file mode 100644 index 00000000..40c253bf --- /dev/null +++ b/youcat/src/main/webapp/openapi/tap/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/youcat/src/main/webapp/openapi/tap/tap-lang.yaml b/youcat/src/main/webapp/openapi/tap/tap-lang.yaml new file mode 100644 index 00000000..c432ae71 --- /dev/null +++ b/youcat/src/main/webapp/openapi/tap/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/youcat/src/main/webapp/openapi/tap/tap-load.yaml b/youcat/src/main/webapp/openapi/tap/tap-load.yaml new file mode 100644 index 00000000..4db5104c --- /dev/null +++ b/youcat/src/main/webapp/openapi/tap/tap-load.yaml @@ -0,0 +1,44 @@ +post: + operationId: tap-bulk-load + 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 + 401: + $ref: ../vosi/vosi-std-responses.yaml#/not-authenticated + 403: + $ref: ../vosi/vosi-std-responses.yaml#/permission-denied + +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 + + diff --git a/youcat/src/main/webapp/openapi/tap/tap-query.yaml b/youcat/src/main/webapp/openapi/tap/tap-query.yaml new file mode 100644 index 00000000..92e9c204 --- /dev/null +++ b/youcat/src/main/webapp/openapi/tap/tap-query.yaml @@ -0,0 +1,6 @@ +name: QUERY +in: query +description: specify the query +required: true +schema: + type: string diff --git a/youcat/src/main/webapp/openapi/tap/tap-responses.yaml b/youcat/src/main/webapp/openapi/tap/tap-responses.yaml new file mode 100644 index 00000000..cc11415d --- /dev/null +++ b/youcat/src/main/webapp/openapi/tap/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/youcat/src/main/webapp/openapi/tap/tap-sync.yaml b/youcat/src/main/webapp/openapi/tap/tap-sync.yaml new file mode 100644 index 00000000..0099cb04 --- /dev/null +++ b/youcat/src/main/webapp/openapi/tap/tap-sync.yaml @@ -0,0 +1,49 @@ +get: + operationId: sync-query-job-get + tags: + - TAP Query + summary: execute sync query + description: TAP synchronous query endpoint + parameters: + - $ref: ./tap-lang.yaml + - $ref: ./tap-query.yaml + - $ref: ./tap-format.yaml + - $ref: ../dali/dali-maxrec.yaml + - $ref: ../dali/dali-responseformat.yaml + - $ref: ../dali/dali-upload.yaml + responses: + 200: + description: successful response + 303: + description: redirect to the job result (optional) + 400: + $ref: ./tap-responses.yaml#/invalid-query + 401: + $ref: ../vosi/vosi-std-responses.yaml#/not-authenticated + 403: + $ref: ../vosi/vosi-std-responses.yaml#/permission-denied +post: + operationId: sync-query-job-create + tags: + - TAP Query + summary: execute sync query + description: TAP synchronous query endpoint + parameters: + - $ref: ./tap-lang.yaml + - $ref: ./tap-query.yaml + - $ref: ./tap-format.yaml + - $ref: ../dali/dali-maxrec.yaml + - $ref: ../dali/dali-responseformat.yaml + - $ref: ../dali/dali-upload.yaml + responses: + 200: + description: successful response + 303: + description: redirect to the job result (optional) + 400: + $ref: ./tap-responses.yaml#/invalid-query + 401: + $ref: ../vosi/vosi-std-responses.yaml#/not-authenticated + 403: + $ref: ../vosi/vosi-std-responses.yaml#/permission-denied + diff --git a/youcat/src/main/webapp/openapi/uws/uws-job-phase.yaml b/youcat/src/main/webapp/openapi/uws/uws-job-phase.yaml new file mode 100644 index 00000000..f8a6ab3e --- /dev/null +++ b/youcat/src/main/webapp/openapi/uws/uws-job-phase.yaml @@ -0,0 +1,46 @@ +get: + operationId: job-phase-get + tags: + - UWS Job + summary: get a UWS job phase + description: job phase resource + parameters: + - name: jobID + in: path + description: unique job identifier generated by the server + required: true + type: string + responses: + 200: + description: successful response +post: + operationId: job-phase-update + tags: + - UWS Job + summary: change a UWS job phase + description: update job + parameters: + - name: jobID + in: path + description: unique job identifier generated by the server + required: true + type: string + - name: PHASE + in: query + description: attempt to change the phase + required: true + schema: + type: string + enum: [ABORT, RUN] + responses: + 200: + description: phase change successful + 400: + $ref: ./uws-responses.yaml#/invalid-phase-change + 401: + $ref: ../vosi/vosi-std-responses.yaml#/not-authenticated + 403: + $ref: ../vosi/vosi-std-responses.yaml#/permission-denied + 404: + $ref: ../vosi/vosi-std-responses.yaml#/not-found + diff --git a/youcat/src/main/webapp/openapi/uws/uws-job.yaml b/youcat/src/main/webapp/openapi/uws/uws-job.yaml new file mode 100644 index 00000000..169d1732 --- /dev/null +++ b/youcat/src/main/webapp/openapi/uws/uws-job.yaml @@ -0,0 +1,26 @@ +get: + operationId: job-get + tags: + - UWS Job + summary: get a UWS job description + description: job resource + parameters: + - name: jobID + in: path + description: unique job identifier generated by the server + required: true + type: string + - name: WAIT + in: query + description: wait for the specified time in seconds or until the phase changes + required: false + type: integer + responses: + 200: + $ref: ./uws-responses.yaml#/components/schemas/jobDoc + 401: + $ref: ../vosi/vosi-std-responses.yaml#/not-authenticated + 403: + $ref: ../vosi/vosi-std-responses.yaml#/permission-denied + 404: + $ref: ../vosi/vosi-std-responses.yaml#/not-found diff --git a/youcat/src/main/webapp/openapi/uws/uws-responses.yaml b/youcat/src/main/webapp/openapi/uws/uws-responses.yaml new file mode 100644 index 00000000..00d70f94 --- /dev/null +++ b/youcat/src/main/webapp/openapi/uws/uws-responses.yaml @@ -0,0 +1,37 @@ +# UWS create job response +created: + description: standard UWS 1.1 redirect to the created job URL + headers: + location: + schema: + type: string + format: uri +invalid-phase-change: + description: the requested phase change is invalid + content: + text/plain: + schema: + type: string +job-listing: + description: list of jobs owned by the caller + content: + text/xml: + schema: + type: object + xml: + name: jobs + prefix: uws + namespace: http://www.ivoa.net/xml/UWS/v1.0 + +components: + schemas: + jobDoc: + description: a single UWS Job + content: + text/xml: + schema: + type: object + xml: + name: job + prefix: uws + namespace: http://www.ivoa.net/xml/UWS/v1.0 diff --git a/youcat/src/main/webapp/openapi/vosi/vosi-capabilities.yaml b/youcat/src/main/webapp/openapi/vosi/vosi-capabilities.yaml new file mode 100644 index 00000000..145da31b --- /dev/null +++ b/youcat/src/main/webapp/openapi/vosi/vosi-capabilities.yaml @@ -0,0 +1,47 @@ +head: + operationId: probe-capabilities + tags: + - VOSI Capabilities + summary: VOSI Capabilities with SSO-next prototype + description: | + Get standard headers for the service. The standard headers should include + AAI related headers (www-authenticate challenges or x-vo-authenticated + indicator) if applicable, server name and version info, and other + applicable header information. SSO-next: clients use this operation to probe + for available authentication methods. + responses: + 200: + $ref: ./vosi-std-responses.yaml#/authenticated + 401: + $ref: ./vosi-std-responses.yaml#/not-authenticated + 403: + $ref: ./vosi-std-responses.yaml#/authenticated + $ref: ./vosi-std-responses.yaml#/permission-denied +get: + operationId: read-capabilities + tags: + - VOSI + summary: VOSI Capabilities with SSO-next prototype + description: Get the set of VOResource capability descriptions for this service. + responses: + 200: + $ref: '#/components/schemas/capabilities' + $ref: ./vosi-std-responses.yaml#/authenticated + 401: + $ref: ./vosi-std-responses.yaml#/not-authenticated + 403: + $ref: ./vosi-std-responses.yaml#/authenticated + $ref: ./vosi-std-responses.yaml#/permission-denied + +components: + schemas: + capabilities: + description: A VOSI Capabilities document + content: + text/xml: + schema: + type: object + xml: + name: capabilities + prefix: vosi + namespace: http://www.ivoa.net/xml/VOSICapabilities/v1.0 diff --git a/youcat/src/main/webapp/openapi/vosi/vosi-std-responses.yaml b/youcat/src/main/webapp/openapi/vosi/vosi-std-responses.yaml new file mode 100644 index 00000000..853a6b66 --- /dev/null +++ b/youcat/src/main/webapp/openapi/vosi/vosi-std-responses.yaml @@ -0,0 +1,49 @@ +# standard +authenticated: + description: a response header indicating that authentication was successful + headers: + x-vo-authenticated: + schema: + type: string + +not-authenticated: + description: authentication is required and current attempt failed + headers: + www-authenticate: + schema: + type: string + +permission-denied: + description: caller not authorized to perform operation + content: + text/plain: + schema: + type: string + +bad-request: + description: invalid request/input + content: + text/plain: + schema: + type: string + +not-found: + description: resource not found + content: + text/plain: + schema: + type: string + +not-implemented: + description: this response indicates that the service does not support this operation + content: + text/plain: + schema: + type: string + +too-large: + description: the request content exceeds a server-side limitation on size + content: + text/plain: + schema: + type: string diff --git a/youcat/src/main/webapp/openapi/vosi/vosi-table.yaml b/youcat/src/main/webapp/openapi/vosi/vosi-table.yaml new file mode 100644 index 00000000..4c5b4c4b --- /dev/null +++ b/youcat/src/main/webapp/openapi/vosi/vosi-table.yaml @@ -0,0 +1,128 @@ +get: + operationId: read-table-metadata + tags: + - VOSI table metadata + summary: get metadata for the specified table + description: provides the table metadata for a single schema or table + parameters: + - in: path + name: name + description: a single schema name or table name as provided in tap_schema + required: true + schema: + type: string + responses: + 200: + $ref: '#/components/schemas/tableDoc' + 401: + $ref: ./vosi-std-responses.yaml#/not-authenticated + 403: + $ref: ./vosi-std-responses.yaml#/permission-denied + 404: + $ref: ./vosi-std-responses.yaml#/not-found +post: + operationId: update-table + tags: + - VOSI table metadata + summary: proto - update table metadata and/or content (optional) + description: update the table metadata from a table description; may include rows to append if input format supports it + parameters: + - in: path + name: name + description: the fully qualified name of the table to create + required: true + schema: + type: string + requestBody: + description: a table description + $ref: '#/components/schemas/tableDoc' + responses: + 204: + description: table updated + 400: + $ref: ./vosi-std-responses.yaml#/bad-request + 401: + $ref: ./vosi-std-responses.yaml#/not-authenticated + 403: + $ref: ./vosi-std-responses.yaml#/permission-denied + 404: + $ref: ./vosi-std-responses.yaml#/not-found + 405: + $ref: ./vosi-std-responses.yaml#/not-implemented + 413: + $ref: ./vosi-std-responses.yaml#/too-large +put: + operationId: create-table + tags: + - VOSI table metadata + summary: proto - create table (optional) + description: create table from a table description; may include rows if input format supports it + parameters: + - in: path + name: name + description: the fully qualified name of the table to create + required: true + schema: + type: string + requestBody: + description: a table description + $ref: '#/components/schemas/tableDoc' + responses: + 201: + description: table created + 400: + $ref: ./vosi-std-responses.yaml#/bad-request + 401: + $ref: ./vosi-std-responses.yaml#/not-authenticated + 403: + $ref: ./vosi-std-responses.yaml#/permission-denied + 404: + $ref: ./vosi-std-responses.yaml#/not-found + 405: + $ref: ./vosi-std-responses.yaml#/not-implemented + 413: + $ref: ./vosi-std-responses.yaml#/too-large +delete: + operationId: delete-table + tags: + - VOSI table metadata + summary: proto - delete table (optional) + description: delete table by name + parameters: + - name: name + in: path + description: the table to delete + required: true + schema: + type: string + responses: + 204: + description: table dropped + 401: + $ref: ./vosi-std-responses.yaml#/not-authenticated + 403: + $ref: ./vosi-std-responses.yaml#/permission-denied + 404: + $ref: ./vosi-std-responses.yaml#/not-found + 405: + $ref: ./vosi-std-responses.yaml#/not-implemented + +components: + schemas: + tableDoc: + description: metadata for the specified schema or table + content: + text/xml: + schema: + type: object + xml: + name: table + prefix: vosi + namespace: http://www.ivoa.net/xml/VOSITables/v1.0 + application/x-votable+xml: + schema: + type: object + xml: + name: VOTABLE + namespace: http://www.ivoa.net/xml/VOTable/v1.3 + diff --git a/youcat/src/main/webapp/openapi/vosi/vosi-tableset.yaml b/youcat/src/main/webapp/openapi/vosi/vosi-tableset.yaml new file mode 100644 index 00000000..4a27765e --- /dev/null +++ b/youcat/src/main/webapp/openapi/vosi/vosi-tableset.yaml @@ -0,0 +1,37 @@ +get: + operationId: get-tableset + tags: + - VOSI table metadata + summary: VOSI TableSet + description: Provides the table metadata in the form of a TableSet description + parameters: + - name: detail + in: query + description: level of detail requested + required: false + schema: + type: string + enum: [min, max] + responses: + 200: + $ref: '#/components/schemas/tablesetDoc' + 400: + $ref: ./vosi-std-responses.yaml#/bad-request + 401: + $ref: ./vosi-std-responses.yaml#/not-authenticated + 403: + $ref: ./vosi-std-responses.yaml#/permission-denied + +components: + schemas: + tablesetDoc: + description: metadata for schemas and tables + content: + text/xml: + schema: + type: object + xml: + name: tableset + prefix: vosi + namespace: http://www.ivoa.net/xml/VOSITables/v1.0 + From 718c8fd56585e6b25737b511239cf28f7a75de0a Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Thu, 22 May 2025 10:35:30 -0700 Subject: [PATCH 10/23] youcat: openapi docs synced with ivoa-std versions --- youcat/openapi-linter | 3 ++ youcat/rsync-openapi-components.sh | 17 +++++++ youcat/src/main/webapp/openapi.yaml | 7 +++ .../main/webapp/openapi/dali/dali-maxrec.yaml | 2 + .../main/webapp/openapi/dali/dali-upload.yaml | 3 ++ .../webapp/openapi/vosi/vosi-table-ops.yaml | 48 +++++++++++++++++++ 6 files changed, 80 insertions(+) create mode 100755 youcat/openapi-linter create mode 100755 youcat/rsync-openapi-components.sh create mode 100644 youcat/src/main/webapp/openapi/vosi/vosi-table-ops.yaml diff --git a/youcat/openapi-linter b/youcat/openapi-linter new file mode 100755 index 00000000..74abd9a9 --- /dev/null +++ b/youcat/openapi-linter @@ -0,0 +1,3 @@ +#!/bin/bash + +cd src/main/webapp && docker run --rm -v $PWD:/work:ro dshanley/vacuum lint -d openapi.yaml diff --git a/youcat/rsync-openapi-components.sh b/youcat/rsync-openapi-components.sh new file mode 100755 index 00000000..1662562c --- /dev/null +++ b/youcat/rsync-openapi-components.sh @@ -0,0 +1,17 @@ +#!/bin/bash + +VOSI=$HOME/work/dev/ivoa-std/VOSI.git +DALI=$HOME/work/dev/ivoa-std/DALI.git +TAP=$HOME/work/dev/ivoa-std/TAP.git + +ARGS="$1 -avu --delete" + +echo "rsync components..." +rsync $ARGS $VOSI/openapi/ src/main/webapp/openapi/vosi/ +rsync $ARGS $DALI/openapi/ src/main/webapp/openapi/dali/ +rsync $ARGS $TAP/openapi/ src/main/webapp/openapi/tap/ +echo + +echo "diff TAP API..." +diff ${TAP}/openapi.yaml src/main/webapp/openapi.yaml + diff --git a/youcat/src/main/webapp/openapi.yaml b/youcat/src/main/webapp/openapi.yaml index 3eef898c..396a8f1c 100644 --- a/youcat/src/main/webapp/openapi.yaml +++ b/youcat/src/main/webapp/openapi.yaml @@ -28,3 +28,10 @@ paths: /tables/{name}: $ref: ./openapi/vosi/vosi-table.yaml +# optional endpoint: allowed to return 404 or 405 + /table-update: + $ref: ./openapi/vosi/vosi-table-ops.yaml + /table-update/{jobID}: + $ref: ./openapi/uws/uws-job.yaml + /table-update/{jobID}/phase: + $ref: ./openapi/uws/uws-job-phase.yaml diff --git a/youcat/src/main/webapp/openapi/dali/dali-maxrec.yaml b/youcat/src/main/webapp/openapi/dali/dali-maxrec.yaml index 9260433f..954c925a 100644 --- a/youcat/src/main/webapp/openapi/dali/dali-maxrec.yaml +++ b/youcat/src/main/webapp/openapi/dali/dali-maxrec.yaml @@ -4,3 +4,5 @@ description: request a specific limit on number of rows to return schema: type: integer format: int64 + minimum: 0 + exclusiveMinimum: false diff --git a/youcat/src/main/webapp/openapi/dali/dali-upload.yaml b/youcat/src/main/webapp/openapi/dali/dali-upload.yaml index 415518b8..2a641583 100644 --- a/youcat/src/main/webapp/openapi/dali/dali-upload.yaml +++ b/youcat/src/main/webapp/openapi/dali/dali-upload.yaml @@ -5,3 +5,6 @@ description: | uploaded and used in the request schema: type: string + # {table name},{location} + # pattern is {1+ word characters},{1+ non-whitespace characters} + pattern: '^[a-zA-Z]\w*,\S+$' diff --git a/youcat/src/main/webapp/openapi/vosi/vosi-table-ops.yaml b/youcat/src/main/webapp/openapi/vosi/vosi-table-ops.yaml new file mode 100644 index 00000000..a7394d94 --- /dev/null +++ b/youcat/src/main/webapp/openapi/vosi/vosi-table-ops.yaml @@ -0,0 +1,48 @@ +get: + operationId: table-ops-job-list + tags: + - Table Operations + summary: list async table update jobs + description: async job listing + parameters: + responses: + 200: + $ref: ../uws/uws-responses.yaml#/job-listing + 401: + $ref: ./vosi-std-responses.yaml#/not-authenticated + 403: + $ref: ./vosi-std-responses.yaml#/permission-denied +post: + operationId: table-ops-job-create + tags: + - Table Operations + summary: create async table update job + description: TAP asynchronous table update (create UWS Job) + parameters: + - name: TABLE + in: query + description: a single table name as provided in tap_schema + required: true + schema: + type: string + - name: INDEX + in: query + description: create index operation; value is a column name in the table + required: false + schema: + type: string + - name: UNIQUE + in: query + description: qualifier for INDEX to create a unique index + required: false + schema: + type: boolean + responses: + 303: + $ref: ../uws/uws-responses.yaml#/created + 401: + $ref: ./vosi-std-responses.yaml#/not-authenticated + 403: + $ref: ./vosi-std-responses.yaml#/permission-denied + 404: + $ref: ./vosi-std-responses.yaml#/not-found From eb2ab9852bd3d259744b877a5e76f28148e82268 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Mon, 26 May 2025 09:26:15 -0700 Subject: [PATCH 11/23] youcat: add customm CADC styling to API docs --- youcat/src/main/webapp/index.html | 49 +++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/youcat/src/main/webapp/index.html b/youcat/src/main/webapp/index.html index 43662f29..7c14733b 100644 --- a/youcat/src/main/webapp/index.html +++ b/youcat/src/main/webapp/index.html @@ -7,6 +7,55 @@ youcat API + From d7b6bd4b4483874298054747d893616f9c2fc518 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Mon, 26 May 2025 14:20:16 -0700 Subject: [PATCH 12/23] youcat: add required version attribute --- youcat/VERSION | 2 +- youcat/src/main/webapp/openapi.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/youcat/VERSION b/youcat/VERSION index f537ac83..a20b566a 100644 --- a/youcat/VERSION +++ b/youcat/VERSION @@ -1,6 +1,6 @@ ## deployable containers have a semantic and build tag # semantic version tag: major.minor # build version tag: timestamp -VER=0.7.4 +VER=0.7.5 TAGS="${VER} ${VER}-$(date --utc +"%Y%m%dT%H%M%S")" unset VER diff --git a/youcat/src/main/webapp/openapi.yaml b/youcat/src/main/webapp/openapi.yaml index 396a8f1c..21b4efb5 100644 --- a/youcat/src/main/webapp/openapi.yaml +++ b/youcat/src/main/webapp/openapi.yaml @@ -1,7 +1,7 @@ openapi: 3.1.0 info: title: prototype TAP-1.2 with user managed tables - #version: "1.2" + version: '0.7.5' description: | This is the WD-TAP-1.2 API specification with components imported from VOSI, UWS, and DALI. From 36c20f1a5955b38a5127efe0acd6488af3c46607 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Fri, 30 May 2025 14:05:20 -0700 Subject: [PATCH 13/23] merge old service description into openapi docs --- youcat/src/main/webapp/index.html | 51 ++++++++++++++++++++++++++++- youcat/src/main/webapp/openapi.yaml | 49 +++++++++++++++++++++++---- 2 files changed, 93 insertions(+), 7 deletions(-) diff --git a/youcat/src/main/webapp/index.html b/youcat/src/main/webapp/index.html index 43662f29..47c2904a 100644 --- a/youcat/src/main/webapp/index.html +++ b/youcat/src/main/webapp/index.html @@ -6,7 +6,56 @@ - youcat API + YouCat API + diff --git a/youcat/src/main/webapp/openapi.yaml b/youcat/src/main/webapp/openapi.yaml index 396a8f1c..cb1bc6c1 100644 --- a/youcat/src/main/webapp/openapi.yaml +++ b/youcat/src/main/webapp/openapi.yaml @@ -1,15 +1,52 @@ openapi: 3.1.0 info: - title: prototype TAP-1.2 with user managed tables - #version: "1.2" + title: | + YouCat: a TAP service with user-owned and created tables. + version: "0.7.5" description: | - This is the WD-TAP-1.2 API specification with components imported from - VOSI, UWS, and DALI. + This service implements the WD-TAP-1.2 API specification with components imported from + VOSI, UWS, and DALI. Querying is completely compatible with the + TAP-1.1 Recommendation. + + YouCat supports user management of permissions at both the schema and table level. A schema + owner is set when a YouCat allocation is created by the service operator. A table owner is + the user who created the table. Owners can set a flag for anonymous reading and can set + groups for read-only and read-write permissons. + + The following describes the three types of grants: + + {schema|table}.anon-read = false|true : true grants read-only permission to anonymous callers + + {schema|table}.read-only = NULL | {group URI} : grant read-only permission to a group + + {schema|table}.read-write = NULL | {group URI} : grant read-write permission to a group + + What these grants mean: + + read-only permission on a schema allows the TAP API to expose table existence and metadata + + read-only permission on table: allows the TAP API to expose content of a table (TAP query) + + read-write permissions on a schema: read-only + create table + + read-write permission on a table: read-only + create index, append rows, update (tap_schema) metadata + + owner of a schema has: read-write + drop (any) tables + + owner of a table has: read-write + drop table + + owner of a schema: change permissions on schema and (any) tables + + owner of a table: change permissions on table + + Group URIs are in the format: ivo://cadc.nrc.ca/gms?groupName + + Note: Previous versions documented a /load endpoint for bulk-loading table content (rows); that + endpoint is still supported but not documented below because it is not expected to be part of the + TAP-1.2 specification. servers: - url: /youcat -## any of the $ref values below can be URLs to external (standard) OpenAPI components - paths: /capabilities: $ref: ./openapi/vosi/vosi-capabilities.yaml From 47d15b1782881f0cfcf09bf9e8052edc4cb50640 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Fri, 30 May 2025 14:29:38 -0700 Subject: [PATCH 14/23] add note about undocumented permissions endpoint --- youcat/src/main/webapp/openapi.yaml | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/youcat/src/main/webapp/openapi.yaml b/youcat/src/main/webapp/openapi.yaml index 99f87d22..85433f46 100644 --- a/youcat/src/main/webapp/openapi.yaml +++ b/youcat/src/main/webapp/openapi.yaml @@ -43,7 +43,11 @@ info: Note: Previous versions documented a /load endpoint for bulk-loading table content (rows); that endpoint is still supported but not documented below because it is not expected to be part of the - TAP-1.2 specification. + TAP-1.2 specification (TBD). + + Note: Previous versions documented a /permissions endpoint for viewign and modifying schema and table + permissions; that endpoint is still supported but not documented below because it is not expected to + be part of the TAP-1.2 specification (TBD). servers: - url: /youcat From 8fbc608363452b0024365942a4775ee13f87db0b Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Tue, 17 Feb 2026 10:06:55 -0800 Subject: [PATCH 15/23] added some padding to the swagger-ui div --- youcat/src/main/webapp/index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/youcat/src/main/webapp/index.html b/youcat/src/main/webapp/index.html index 47c2904a..840d229b 100644 --- a/youcat/src/main/webapp/index.html +++ b/youcat/src/main/webapp/index.html @@ -36,7 +36,7 @@ .swagger-ui .wrapper, .swagger-ui .opblock-tag { - padding: 0; + padding: 10; } .swagger-ui .info .title { From 93c3948fab1795533f2a460d8692ce282d4f6456 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Thu, 26 Feb 2026 14:04:27 -0800 Subject: [PATCH 16/23] youcat: import latest openapi components from ivoa-std --- youcat/openapi-linter | 9 +- youcat/rsync-openapi-components.sh | 14 +-- youcat/src/main/webapp/openapi.yaml | 29 +++-- .../main/webapp/openapi/dali/dali-maxrec.yaml | 3 +- .../main/webapp/openapi/dali/dali-upload.yaml | 6 +- .../main/webapp/openapi/tap/tap-async.yaml | 16 +-- .../src/main/webapp/openapi/tap/tap-lang.yaml | 1 + .../main/webapp/openapi/tap/tap-query.yaml | 1 + .../webapp/openapi/tap/tap-responses.yaml | 14 ++- .../main/webapp/openapi/tap/tap-result.yaml | 57 +++++++++ .../src/main/webapp/openapi/tap/tap-sync.yaml | 24 ++-- .../webapp/openapi/uws/uws-job-phase.yaml | 25 ++-- .../src/main/webapp/openapi/uws/uws-job.yaml | 14 ++- .../webapp/openapi/uws/uws-responses.yaml | 48 ++++++-- .../openapi/vosi/vosi-capabilities.yaml | 29 +++-- .../webapp/openapi/vosi/vosi-table-ops.yaml | 48 -------- .../main/webapp/openapi/vosi/vosi-table.yaml | 110 +++++++++++++----- .../webapp/openapi/vosi/vosi-tableset.yaml | 41 ++++++- 18 files changed, 323 insertions(+), 166 deletions(-) create mode 100644 youcat/src/main/webapp/openapi/tap/tap-result.yaml delete mode 100644 youcat/src/main/webapp/openapi/vosi/vosi-table-ops.yaml diff --git a/youcat/openapi-linter b/youcat/openapi-linter index 74abd9a9..654ad8ca 100755 --- a/youcat/openapi-linter +++ b/youcat/openapi-linter @@ -1,3 +1,10 @@ #!/bin/bash -cd src/main/webapp && docker run --rm -v $PWD:/work:ro dshanley/vacuum lint -d openapi.yaml +test -d src/main/webapp && cd src/main/webapp + +if [[ "$1" == "-it" ]]; then + docker run -it --rm -v $PWD:/work:ro dshanley/vacuum /bin/bash +else + docker run --rm -v $PWD:/work:ro dshanley/vacuum lint --no-clip -d openapi.yaml +fi + diff --git a/youcat/rsync-openapi-components.sh b/youcat/rsync-openapi-components.sh index 1662562c..1fcf4198 100755 --- a/youcat/rsync-openapi-components.sh +++ b/youcat/rsync-openapi-components.sh @@ -4,14 +4,10 @@ VOSI=$HOME/work/dev/ivoa-std/VOSI.git DALI=$HOME/work/dev/ivoa-std/DALI.git TAP=$HOME/work/dev/ivoa-std/TAP.git -ARGS="$1 -avu --delete" +ARGS="$1 -avc --delete" -echo "rsync components..." -rsync $ARGS $VOSI/openapi/ src/main/webapp/openapi/vosi/ -rsync $ARGS $DALI/openapi/ src/main/webapp/openapi/dali/ -rsync $ARGS $TAP/openapi/ src/main/webapp/openapi/tap/ -echo - -echo "diff TAP API..." -diff ${TAP}/openapi.yaml src/main/webapp/openapi.yaml +rsync $ARGS $VOSI/openapi/vosi src/main/webapp/openapi/ +rsync $ARGS $DALI/openapi/dali src/main/webapp/openapi/ +rsync $ARGS $TAP/openapi/uws src/main/webapp/openapi/ +rsync $ARGS $TAP/openapi/tap src/main/webapp/openapi/ diff --git a/youcat/src/main/webapp/openapi.yaml b/youcat/src/main/webapp/openapi.yaml index 85433f46..d10fb95d 100644 --- a/youcat/src/main/webapp/openapi.yaml +++ b/youcat/src/main/webapp/openapi.yaml @@ -2,7 +2,7 @@ openapi: 3.1.0 info: title: | YouCat: a TAP service with user-owned and created tables. - version: "0.7.5" + version: "0.9.2" description: | This service implements the WD-TAP-1.2 API specification with components imported from VOSI, UWS, and DALI. Querying is completely compatible with the @@ -45,16 +45,18 @@ info: endpoint is still supported but not documented below because it is not expected to be part of the TAP-1.2 specification (TBD). - Note: Previous versions documented a /permissions endpoint for viewign and modifying schema and table + Note: Previous versions documented a /permissions endpoint for viewing and modifying schema and table permissions; that endpoint is still supported but not documented below because it is not expected to be part of the TAP-1.2 specification (TBD). servers: - url: /youcat -paths: - /capabilities: - $ref: ./openapi/vosi/vosi-capabilities.yaml +tags: + - name: VOSI Capabilities + - name: VOSI Table Metadata + - name: TAP Query +paths: /sync: $ref: ./openapi/tap/tap-sync.yaml /async: @@ -63,15 +65,20 @@ paths: $ref: ./openapi/uws/uws-job.yaml /async/{jobID}/phase: $ref: ./openapi/uws/uws-job-phase.yaml + /async/{jobID}/results/result: + $ref: ./openapi/tap/tap-result.yaml + + /capabilities: + $ref: ./openapi/vosi/vosi-capabilities.yaml /tables: $ref: ./openapi/vosi/vosi-tableset.yaml /tables/{name}: $ref: ./openapi/vosi/vosi-table.yaml - /table-update: - $ref: ./openapi/vosi/vosi-table-ops.yaml - /table-update/{jobID}: - $ref: ./openapi/uws/uws-job.yaml - /table-update/{jobID}/phase: - $ref: ./openapi/uws/uws-job-phase.yaml + #/table-update: + # $ref: ./openapi/vosi/vosi-table-ops.yaml + #/table-update/{jobID}: + # $ref: ./openapi/uws/uws-job.yaml + #/table-update/{jobID}/phase: + # $ref: ./openapi/uws/uws-job-phase.yaml diff --git a/youcat/src/main/webapp/openapi/dali/dali-maxrec.yaml b/youcat/src/main/webapp/openapi/dali/dali-maxrec.yaml index 954c925a..42d5ac76 100644 --- a/youcat/src/main/webapp/openapi/dali/dali-maxrec.yaml +++ b/youcat/src/main/webapp/openapi/dali/dali-maxrec.yaml @@ -1,6 +1,7 @@ name: MAXREC in: query -description: request a specific limit on number of rows to return +description: | + request a specific limit on number of records to return schema: type: integer format: int64 diff --git a/youcat/src/main/webapp/openapi/dali/dali-upload.yaml b/youcat/src/main/webapp/openapi/dali/dali-upload.yaml index 2a641583..ef9f0185 100644 --- a/youcat/src/main/webapp/openapi/dali/dali-upload.yaml +++ b/youcat/src/main/webapp/openapi/dali/dali-upload.yaml @@ -1,10 +1,8 @@ name: UPLOAD in: query description: | - specify comma-separated name,location pair for a temporary table to be - uploaded and used in the request + specify a comma-separated name,location pair for a temporary + resource to be uploaded and used in the request schema: type: string - # {table name},{location} - # pattern is {1+ word characters},{1+ non-whitespace characters} pattern: '^[a-zA-Z]\w*,\S+$' diff --git a/youcat/src/main/webapp/openapi/tap/tap-async.yaml b/youcat/src/main/webapp/openapi/tap/tap-async.yaml index 7659c9e4..d42e0c97 100644 --- a/youcat/src/main/webapp/openapi/tap/tap-async.yaml +++ b/youcat/src/main/webapp/openapi/tap/tap-async.yaml @@ -2,21 +2,21 @@ get: operationId: query-job-list tags: - TAP Query - summary: list async queries + summary: list queries (UWS jobs) description: TAP asynchronous query endpoint (list UWS Jobs) parameters: responses: - 200: + '200': $ref: ../uws/uws-responses.yaml#/job-listing - 401: + '401': $ref: ../vosi/vosi-std-responses.yaml#/not-authenticated - 403: + '403': $ref: ../vosi/vosi-std-responses.yaml#/permission-denied post: operationId: query-job-create tags: - TAP Query - summary: create async query + summary: create async query (UWS job) description: TAP asynchronous query endpoint (create UWS Job) parameters: - $ref: ./tap-lang.yaml @@ -26,9 +26,9 @@ post: - $ref: ../dali/dali-responseformat.yaml - $ref: ../dali/dali-upload.yaml responses: - 303: + '303': $ref: ../uws/uws-responses.yaml#/created - 401: + '401': $ref: ../vosi/vosi-std-responses.yaml#/not-authenticated - 403: + '403': $ref: ../vosi/vosi-std-responses.yaml#/permission-denied diff --git a/youcat/src/main/webapp/openapi/tap/tap-lang.yaml b/youcat/src/main/webapp/openapi/tap/tap-lang.yaml index c432ae71..99d3bb4c 100644 --- a/youcat/src/main/webapp/openapi/tap/tap-lang.yaml +++ b/youcat/src/main/webapp/openapi/tap/tap-lang.yaml @@ -4,3 +4,4 @@ description: specify the query language used in the QUERY parameter required: true schema: type: string + example: ADQL diff --git a/youcat/src/main/webapp/openapi/tap/tap-query.yaml b/youcat/src/main/webapp/openapi/tap/tap-query.yaml index 92e9c204..934213a7 100644 --- a/youcat/src/main/webapp/openapi/tap/tap-query.yaml +++ b/youcat/src/main/webapp/openapi/tap/tap-query.yaml @@ -4,3 +4,4 @@ description: specify the query required: true schema: type: string + example: select * from tap_schema.tables diff --git a/youcat/src/main/webapp/openapi/tap/tap-responses.yaml b/youcat/src/main/webapp/openapi/tap/tap-responses.yaml index cc11415d..14ccd462 100644 --- a/youcat/src/main/webapp/openapi/tap/tap-responses.yaml +++ b/youcat/src/main/webapp/openapi/tap/tap-responses.yaml @@ -2,6 +2,16 @@ invalid-query: description: the requested TAP query job is invalid; this is usually the ADQL query content: - text/plain: + application/x-votable+xml: schema: - type: string + type: object + xml: + name: VOTABLE + namespace: http://www.ivoa.net/xml/VOTable/v1.3 + example: | + + + Table 'Y' is not found in TAP schema + + diff --git a/youcat/src/main/webapp/openapi/tap/tap-result.yaml b/youcat/src/main/webapp/openapi/tap/tap-result.yaml new file mode 100644 index 00000000..b1cba58a --- /dev/null +++ b/youcat/src/main/webapp/openapi/tap/tap-result.yaml @@ -0,0 +1,57 @@ +get: + operationId: tap-result + tags: + - TAP Query + summary: async query result + description: download async query result for a completed job + parameters: + - name: jobID + in: path + description: unique job identifier generated by the server + required: true + type: string + example: a1b2c3 + responses: + '200': + $ref: '#/components/schemas/queryResult' + '303': + description: redirect to the stored result (optional) + '401': + $ref: ../vosi/vosi-std-responses.yaml#/not-authenticated + '403': + $ref: ../vosi/vosi-std-responses.yaml#/permission-denied + '404': + $ref: ../vosi/vosi-std-responses.yaml#/not-found + +components: + schemas: + queryResult: + description: query result (table) + content: + application/x-votable+xml: + schema: + type: object + xml: + name: VOTABLE + namespace: http://www.ivoa.net/xml/VOTable/v1.3 + example: | + + +
+ + schema name for reference to tap_schema.schemas + + + lists the utypes of schemas in the tableset + + + describes schemas in the tableset + + + recommended sort order when listing schemas + + +
+ + diff --git a/youcat/src/main/webapp/openapi/tap/tap-sync.yaml b/youcat/src/main/webapp/openapi/tap/tap-sync.yaml index 0099cb04..d385a2d5 100644 --- a/youcat/src/main/webapp/openapi/tap/tap-sync.yaml +++ b/youcat/src/main/webapp/openapi/tap/tap-sync.yaml @@ -12,15 +12,15 @@ get: - $ref: ../dali/dali-responseformat.yaml - $ref: ../dali/dali-upload.yaml responses: - 200: - description: successful response - 303: + '200': + $ref: './tap-result.yaml#/components/schemas/queryResult' + '303': description: redirect to the job result (optional) - 400: + '400': $ref: ./tap-responses.yaml#/invalid-query - 401: + '401': $ref: ../vosi/vosi-std-responses.yaml#/not-authenticated - 403: + '403': $ref: ../vosi/vosi-std-responses.yaml#/permission-denied post: operationId: sync-query-job-create @@ -36,14 +36,14 @@ post: - $ref: ../dali/dali-responseformat.yaml - $ref: ../dali/dali-upload.yaml responses: - 200: - description: successful response - 303: + '200': + $ref: './tap-result.yaml#/components/schemas/queryResult' + '303': description: redirect to the job result (optional) - 400: + '400': $ref: ./tap-responses.yaml#/invalid-query - 401: + '401': $ref: ../vosi/vosi-std-responses.yaml#/not-authenticated - 403: + '403': $ref: ../vosi/vosi-std-responses.yaml#/permission-denied diff --git a/youcat/src/main/webapp/openapi/uws/uws-job-phase.yaml b/youcat/src/main/webapp/openapi/uws/uws-job-phase.yaml index f8a6ab3e..0531f9ea 100644 --- a/youcat/src/main/webapp/openapi/uws/uws-job-phase.yaml +++ b/youcat/src/main/webapp/openapi/uws/uws-job-phase.yaml @@ -1,7 +1,7 @@ get: operationId: job-phase-get tags: - - UWS Job + - TAP Query summary: get a UWS job phase description: job phase resource parameters: @@ -10,13 +10,19 @@ get: description: unique job identifier generated by the server required: true type: string + example: a1b2c3 responses: - 200: + '200': description: successful response + content: + text/plain: + schema: + type: string + example: "PENDING" post: operationId: job-phase-update tags: - - UWS Job + - TAP Query summary: change a UWS job phase description: update job parameters: @@ -25,6 +31,7 @@ post: description: unique job identifier generated by the server required: true type: string + example: a1b2c3 - name: PHASE in: query description: attempt to change the phase @@ -32,15 +39,17 @@ post: schema: type: string enum: [ABORT, RUN] + example: RUN + responses: - 200: + '200': description: phase change successful - 400: + '400': $ref: ./uws-responses.yaml#/invalid-phase-change - 401: + '401': $ref: ../vosi/vosi-std-responses.yaml#/not-authenticated - 403: + '403': $ref: ../vosi/vosi-std-responses.yaml#/permission-denied - 404: + '404': $ref: ../vosi/vosi-std-responses.yaml#/not-found diff --git a/youcat/src/main/webapp/openapi/uws/uws-job.yaml b/youcat/src/main/webapp/openapi/uws/uws-job.yaml index 169d1732..682b6efd 100644 --- a/youcat/src/main/webapp/openapi/uws/uws-job.yaml +++ b/youcat/src/main/webapp/openapi/uws/uws-job.yaml @@ -1,7 +1,7 @@ get: operationId: job-get tags: - - UWS Job + - TAP Query summary: get a UWS job description description: job resource parameters: @@ -10,17 +10,19 @@ get: description: unique job identifier generated by the server required: true type: string + example: a1b2c3 - name: WAIT in: query description: wait for the specified time in seconds or until the phase changes required: false type: integer + example: WAIT=60 responses: - 200: - $ref: ./uws-responses.yaml#/components/schemas/jobDoc - 401: + '200': + $ref: ./uws-responses.yaml#/job + '401': $ref: ../vosi/vosi-std-responses.yaml#/not-authenticated - 403: + '403': $ref: ../vosi/vosi-std-responses.yaml#/permission-denied - 404: + '404': $ref: ../vosi/vosi-std-responses.yaml#/not-found diff --git a/youcat/src/main/webapp/openapi/uws/uws-responses.yaml b/youcat/src/main/webapp/openapi/uws/uws-responses.yaml index 00d70f94..e4515cce 100644 --- a/youcat/src/main/webapp/openapi/uws/uws-responses.yaml +++ b/youcat/src/main/webapp/openapi/uws/uws-responses.yaml @@ -22,16 +22,40 @@ job-listing: name: jobs prefix: uws namespace: http://www.ivoa.net/xml/UWS/v1.0 + example: | + + + PENDING + TEST + somebody + 2024-07-16T16:38:33.090Z + + ... + -components: - schemas: - jobDoc: - description: a single UWS Job - content: - text/xml: - schema: - type: object - xml: - name: job - prefix: uws - namespace: http://www.ivoa.net/xml/UWS/v1.0 +job: + description: a single UWS Job + content: + text/xml: + schema: + type: object + xml: + name: job + prefix: uws + namespace: http://www.ivoa.net/xml/UWS/v1.0 + example: | + + loqqxg8jlah0r8wp + somebody + PENDING + 2024-07-17T16:38:33.089Z + 2024-07-16T16:38:33.090Z + + + 28800 + 2024-07-23T16:38:33.089Z + + + + + diff --git a/youcat/src/main/webapp/openapi/vosi/vosi-capabilities.yaml b/youcat/src/main/webapp/openapi/vosi/vosi-capabilities.yaml index 145da31b..b60a3827 100644 --- a/youcat/src/main/webapp/openapi/vosi/vosi-capabilities.yaml +++ b/youcat/src/main/webapp/openapi/vosi/vosi-capabilities.yaml @@ -10,27 +10,24 @@ head: applicable header information. SSO-next: clients use this operation to probe for available authentication methods. responses: - 200: + '200': $ref: ./vosi-std-responses.yaml#/authenticated - 401: + '401': $ref: ./vosi-std-responses.yaml#/not-authenticated - 403: - $ref: ./vosi-std-responses.yaml#/authenticated + '403': $ref: ./vosi-std-responses.yaml#/permission-denied get: operationId: read-capabilities tags: - - VOSI + - VOSI Capabilities summary: VOSI Capabilities with SSO-next prototype description: Get the set of VOResource capability descriptions for this service. responses: - 200: + '200': $ref: '#/components/schemas/capabilities' - $ref: ./vosi-std-responses.yaml#/authenticated - 401: + '401': $ref: ./vosi-std-responses.yaml#/not-authenticated - 403: - $ref: ./vosi-std-responses.yaml#/authenticated + '403': $ref: ./vosi-std-responses.yaml#/permission-denied components: @@ -45,3 +42,15 @@ components: name: capabilities prefix: vosi namespace: http://www.ivoa.net/xml/VOSICapabilities/v1.0 + example: | + + + + https://example.net/tap-service/capabilities + + + ... + diff --git a/youcat/src/main/webapp/openapi/vosi/vosi-table-ops.yaml b/youcat/src/main/webapp/openapi/vosi/vosi-table-ops.yaml deleted file mode 100644 index a7394d94..00000000 --- a/youcat/src/main/webapp/openapi/vosi/vosi-table-ops.yaml +++ /dev/null @@ -1,48 +0,0 @@ -get: - operationId: table-ops-job-list - tags: - - Table Operations - summary: list async table update jobs - description: async job listing - parameters: - responses: - 200: - $ref: ../uws/uws-responses.yaml#/job-listing - 401: - $ref: ./vosi-std-responses.yaml#/not-authenticated - 403: - $ref: ./vosi-std-responses.yaml#/permission-denied -post: - operationId: table-ops-job-create - tags: - - Table Operations - summary: create async table update job - description: TAP asynchronous table update (create UWS Job) - parameters: - - name: TABLE - in: query - description: a single table name as provided in tap_schema - required: true - schema: - type: string - - name: INDEX - in: query - description: create index operation; value is a column name in the table - required: false - schema: - type: string - - name: UNIQUE - in: query - description: qualifier for INDEX to create a unique index - required: false - schema: - type: boolean - responses: - 303: - $ref: ../uws/uws-responses.yaml#/created - 401: - $ref: ./vosi-std-responses.yaml#/not-authenticated - 403: - $ref: ./vosi-std-responses.yaml#/permission-denied - 404: - $ref: ./vosi-std-responses.yaml#/not-found diff --git a/youcat/src/main/webapp/openapi/vosi/vosi-table.yaml b/youcat/src/main/webapp/openapi/vosi/vosi-table.yaml index 4c5b4c4b..2bee6556 100644 --- a/youcat/src/main/webapp/openapi/vosi/vosi-table.yaml +++ b/youcat/src/main/webapp/openapi/vosi/vosi-table.yaml @@ -1,7 +1,8 @@ +# this is the VOSI-1.2 /tables/{tablename} endpoint get: operationId: read-table-metadata tags: - - VOSI table metadata + - VOSI Table Metadata summary: get metadata for the specified table description: provides the table metadata for a single schema or table parameters: @@ -12,18 +13,18 @@ get: schema: type: string responses: - 200: + '200': $ref: '#/components/schemas/tableDoc' - 401: + '401': $ref: ./vosi-std-responses.yaml#/not-authenticated - 403: + '403': $ref: ./vosi-std-responses.yaml#/permission-denied - 404: + '404': $ref: ./vosi-std-responses.yaml#/not-found post: operationId: update-table tags: - - VOSI table metadata + - VOSI Table Metadata summary: proto - update table metadata and/or content (optional) description: update the table metadata from a table description; may include rows to append if input format supports it parameters: @@ -37,24 +38,24 @@ post: description: a table description $ref: '#/components/schemas/tableDoc' responses: - 204: + '204': description: table updated - 400: + '400': $ref: ./vosi-std-responses.yaml#/bad-request - 401: + '401': $ref: ./vosi-std-responses.yaml#/not-authenticated - 403: + '403': $ref: ./vosi-std-responses.yaml#/permission-denied - 404: + '404': $ref: ./vosi-std-responses.yaml#/not-found - 405: + '405': $ref: ./vosi-std-responses.yaml#/not-implemented - 413: + '413': $ref: ./vosi-std-responses.yaml#/too-large put: operationId: create-table tags: - - VOSI table metadata + - VOSI Table Metadata summary: proto - create table (optional) description: create table from a table description; may include rows if input format supports it parameters: @@ -68,24 +69,24 @@ put: description: a table description $ref: '#/components/schemas/tableDoc' responses: - 201: + '201': description: table created - 400: + '400': $ref: ./vosi-std-responses.yaml#/bad-request - 401: + '401': $ref: ./vosi-std-responses.yaml#/not-authenticated - 403: + '403': $ref: ./vosi-std-responses.yaml#/permission-denied - 404: + '404': $ref: ./vosi-std-responses.yaml#/not-found - 405: + '405': $ref: ./vosi-std-responses.yaml#/not-implemented - 413: + '413': $ref: ./vosi-std-responses.yaml#/too-large delete: operationId: delete-table tags: - - VOSI table metadata + - VOSI Table Metadata summary: proto - delete table (optional) description: delete table by name parameters: @@ -96,16 +97,16 @@ delete: schema: type: string responses: - 204: - description: table dropped - 401: + '204': + description: table deleted + '400': + $ref: ./vosi-std-responses.yaml#/bad-request + '401': $ref: ./vosi-std-responses.yaml#/not-authenticated - 403: + '403': $ref: ./vosi-std-responses.yaml#/permission-denied - 404: + '404': $ref: ./vosi-std-responses.yaml#/not-found - 405: - $ref: ./vosi-std-responses.yaml#/not-implemented components: schemas: @@ -119,10 +120,61 @@ components: name: table prefix: vosi namespace: http://www.ivoa.net/xml/VOSITables/v1.0 + example: | + + tap_schema.schemas + description of schemas in this tableset + + schema_name + schema name for reference to tap_schema.schemas + char + indexed + + + utype + lists the utypes of schemas in the tableset + char + + + description + describes schemas in the tableset + char + + + schema_index + recommended sort order when listing schemas + int + + application/x-votable+xml: schema: type: object xml: name: VOTABLE namespace: http://www.ivoa.net/xml/VOTable/v1.3 + example: | + + + + + schema name for reference to tap_schema.schemas + + + lists the utypes of schemas in the tableset + + + describes schemas in the tableset + + + recommended sort order when listing schemas + + +
+ + + diff --git a/youcat/src/main/webapp/openapi/vosi/vosi-tableset.yaml b/youcat/src/main/webapp/openapi/vosi/vosi-tableset.yaml index 4a27765e..cf54408b 100644 --- a/youcat/src/main/webapp/openapi/vosi/vosi-tableset.yaml +++ b/youcat/src/main/webapp/openapi/vosi/vosi-tableset.yaml @@ -1,7 +1,7 @@ get: operationId: get-tableset tags: - - VOSI table metadata + - VOSI Table Metadata summary: VOSI TableSet description: Provides the table metadata in the form of a TableSet description parameters: @@ -13,13 +13,13 @@ get: type: string enum: [min, max] responses: - 200: + '200': $ref: '#/components/schemas/tablesetDoc' - 400: + '400': $ref: ./vosi-std-responses.yaml#/bad-request - 401: + '401': $ref: ./vosi-std-responses.yaml#/not-authenticated - 403: + '403': $ref: ./vosi-std-responses.yaml#/permission-denied components: @@ -34,4 +34,35 @@ components: name: tableset prefix: vosi namespace: http://www.ivoa.net/xml/VOSITables/v1.0 + example: | + + + tap_schema + a special schema to describe TAP-1.1 tablesets + + tap_schema.schemas + description of schemas in this tableset +
+ + tap_schema.tables + description of tables in this tableset +
+ + tap_schema.columns + description of columns in this tableset +
+ + tap_schema.keys + description of foreign keys in this tableset +
+ + tap_schema.key_columns + description of foreign key columns in this tableset +
+ + ... + From 3a1c877687f6219f6790b96b341c8687caeb7422 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Tue, 31 Mar 2026 17:18:12 -0700 Subject: [PATCH 17/23] added deprecated load and permissions endpoints to api docs --- youcat/src/main/webapp/openapi.yaml | 33 ++++++------ .../tap-async-job-phase.yaml} | 6 +-- .../uws-job.yaml => tap/tap-async-job.yaml} | 4 +- .../{tap/tap-load.yaml => youcat-load.yaml} | 28 +++++----- .../webapp/openapi/youcat-permissions.yaml | 54 +++++++++++++++++++ 5 files changed, 91 insertions(+), 34 deletions(-) rename youcat/src/main/webapp/openapi/{uws/uws-job-phase.yaml => tap/tap-async-job-phase.yaml} (90%) rename youcat/src/main/webapp/openapi/{uws/uws-job.yaml => tap/tap-async-job.yaml} (90%) rename youcat/src/main/webapp/openapi/{tap/tap-load.yaml => youcat-load.yaml} (58%) create mode 100644 youcat/src/main/webapp/openapi/youcat-permissions.yaml diff --git a/youcat/src/main/webapp/openapi.yaml b/youcat/src/main/webapp/openapi.yaml index d10fb95d..44c40aa4 100644 --- a/youcat/src/main/webapp/openapi.yaml +++ b/youcat/src/main/webapp/openapi.yaml @@ -41,20 +41,15 @@ info: Group URIs are in the format: ivo://cadc.nrc.ca/gms?groupName - Note: Previous versions documented a /load endpoint for bulk-loading table content (rows); that - endpoint is still supported but not documented below because it is not expected to be part of the - TAP-1.2 specification (TBD). - - Note: Previous versions documented a /permissions endpoint for viewing and modifying schema and table - permissions; that endpoint is still supported but not documented below because it is not expected to - be part of the TAP-1.2 specification (TBD). servers: - url: /youcat tags: + - name: TAP Query - name: VOSI Capabilities - name: VOSI Table Metadata - - name: TAP Query + - name: VOSI Table Operations + - name: Deprecated paths: /sync: @@ -62,9 +57,9 @@ paths: /async: $ref: ./openapi/tap/tap-async.yaml /async/{jobID}: - $ref: ./openapi/uws/uws-job.yaml + $ref: ./openapi/tap/tap-async-job.yaml /async/{jobID}/phase: - $ref: ./openapi/uws/uws-job-phase.yaml + $ref: ./openapi/tap/tap-async-job-phase.yaml /async/{jobID}/results/result: $ref: ./openapi/tap/tap-result.yaml @@ -76,9 +71,15 @@ paths: /tables/{name}: $ref: ./openapi/vosi/vosi-table.yaml - #/table-update: - # $ref: ./openapi/vosi/vosi-table-ops.yaml - #/table-update/{jobID}: - # $ref: ./openapi/uws/uws-job.yaml - #/table-update/{jobID}/phase: - # $ref: ./openapi/uws/uws-job-phase.yaml + /table-ops: + $ref: ./openapi/vosi/vosi-table-ops.yaml + /table-ops/{jobID}: + $ref: ./openapi/vosi/vosi-table-ops-job.yaml + /table-ops/{jobID}/phase: + $ref: ./openapi/vosi/vosi-table-ops-job-phase.yaml + + /load/{name}: + $ref: ./openapi/youcat-load.yaml + /permissions/{name}: + $ref: ./openapi/youcat-permissions.yaml + diff --git a/youcat/src/main/webapp/openapi/uws/uws-job-phase.yaml b/youcat/src/main/webapp/openapi/tap/tap-async-job-phase.yaml similarity index 90% rename from youcat/src/main/webapp/openapi/uws/uws-job-phase.yaml rename to youcat/src/main/webapp/openapi/tap/tap-async-job-phase.yaml index 0531f9ea..3d9031a2 100644 --- a/youcat/src/main/webapp/openapi/uws/uws-job-phase.yaml +++ b/youcat/src/main/webapp/openapi/tap/tap-async-job-phase.yaml @@ -1,5 +1,5 @@ get: - operationId: job-phase-get + operationId: tap-job-phase-get tags: - TAP Query summary: get a UWS job phase @@ -20,7 +20,7 @@ get: type: string example: "PENDING" post: - operationId: job-phase-update + operationId: tap-job-phase-update tags: - TAP Query summary: change a UWS job phase @@ -45,7 +45,7 @@ post: '200': description: phase change successful '400': - $ref: ./uws-responses.yaml#/invalid-phase-change + $ref: ../uws/uws-responses.yaml#/invalid-phase-change '401': $ref: ../vosi/vosi-std-responses.yaml#/not-authenticated '403': diff --git a/youcat/src/main/webapp/openapi/uws/uws-job.yaml b/youcat/src/main/webapp/openapi/tap/tap-async-job.yaml similarity index 90% rename from youcat/src/main/webapp/openapi/uws/uws-job.yaml rename to youcat/src/main/webapp/openapi/tap/tap-async-job.yaml index 682b6efd..1f7fb9cc 100644 --- a/youcat/src/main/webapp/openapi/uws/uws-job.yaml +++ b/youcat/src/main/webapp/openapi/tap/tap-async-job.yaml @@ -1,5 +1,5 @@ get: - operationId: job-get + operationId: tap-job-get tags: - TAP Query summary: get a UWS job description @@ -19,7 +19,7 @@ get: example: WAIT=60 responses: '200': - $ref: ./uws-responses.yaml#/job + $ref: ../uws/uws-responses.yaml#/job '401': $ref: ../vosi/vosi-std-responses.yaml#/not-authenticated '403': diff --git a/youcat/src/main/webapp/openapi/tap/tap-load.yaml b/youcat/src/main/webapp/openapi/youcat-load.yaml similarity index 58% rename from youcat/src/main/webapp/openapi/tap/tap-load.yaml rename to youcat/src/main/webapp/openapi/youcat-load.yaml index 4db5104c..e9deb605 100644 --- a/youcat/src/main/webapp/openapi/tap/tap-load.yaml +++ b/youcat/src/main/webapp/openapi/youcat-load.yaml @@ -1,7 +1,9 @@ post: - operationId: tap-bulk-load - summary: bulk load or row data - description: TAP synchronous bulk load endpoint + operationId: youcat-bulk-load + tags: + - Deprecated + summary: bulk load or row data (deprecated) + description: youcat synchronous bulk load endpoint (deprecated) parameters: - name: name in: path @@ -10,22 +12,22 @@ post: schema: type: string requestBody: - required: true - $ref: '#/components/schemas/tableRows' + $ref: '#/components/schemas/tableRows' responses: - 200: - description: | - rows loaded; - TBD: both partial or complete are possible - 401: - $ref: ../vosi/vosi-std-responses.yaml#/not-authenticated - 403: - $ref: ../vosi/vosi-std-responses.yaml#/permission-denied + '200': + description: | + rows loaded; + TBD: both partial or complete are possible + '401': + $ref: ./vosi/vosi-std-responses.yaml#/not-authenticated + '403': + $ref: ./vosi/vosi-std-responses.yaml#/permission-denied components: schemas: tableRows: + description: tabular content with rows to be appended to the table content: text/tab-separated-values: schema: diff --git a/youcat/src/main/webapp/openapi/youcat-permissions.yaml b/youcat/src/main/webapp/openapi/youcat-permissions.yaml new file mode 100644 index 00000000..082714f6 --- /dev/null +++ b/youcat/src/main/webapp/openapi/youcat-permissions.yaml @@ -0,0 +1,54 @@ +get: + operationId: youcat-get-permissions + tags: + - Deprecated + summary: get permissions (deprecated) + description: youcat get schema and table permissions endpoint (deprecated) + parameters: + - name: name + in: path + description: a single schema or table name as provided in tap_schema + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/schemas/permissionDoc' + '401': + $ref: ./vosi/vosi-std-responses.yaml#/not-authenticated + '403': + $ref: ./vosi/vosi-std-responses.yaml#/permission-denied +post: + operationId: youcat-set-permissions + tags: + - Deprecated + summary: set permissions (deprecated) + description: youcat set schema and table permissions endpoint (deprecated) + parameters: + - name: name + in: path + description: a single schema or table name as provided in tap_schema + required: true + schema: + type: string + requestBody: + $ref: '#/components/schemas/permissionDoc' + + responses: + '200': + description: | + rows loaded; + TBD: both partial or complete are possible + '401': + $ref: ./vosi/vosi-std-responses.yaml#/not-authenticated + '403': + $ref: ./vosi/vosi-std-responses.yaml#/permission-denied + +components: + schemas: + permissionDoc: + description: document with permissions settings + content: + text/plain: + schema: + type: string From 2b2ce3336129486001fe57ca2d0f4fcfe6d932fe Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Tue, 31 Mar 2026 17:21:38 -0700 Subject: [PATCH 18/23] include vosi-table-ops --- .../vosi/vosi-table-ops-job-phase.yaml | 55 +++++++++++++++++ .../openapi/vosi/vosi-table-ops-job.yaml | 28 +++++++++ .../webapp/openapi/vosi/vosi-table-ops.yaml | 61 +++++++++++++++++++ 3 files changed, 144 insertions(+) create mode 100644 youcat/src/main/webapp/openapi/vosi/vosi-table-ops-job-phase.yaml create mode 100644 youcat/src/main/webapp/openapi/vosi/vosi-table-ops-job.yaml create mode 100644 youcat/src/main/webapp/openapi/vosi/vosi-table-ops.yaml diff --git a/youcat/src/main/webapp/openapi/vosi/vosi-table-ops-job-phase.yaml b/youcat/src/main/webapp/openapi/vosi/vosi-table-ops-job-phase.yaml new file mode 100644 index 00000000..83790608 --- /dev/null +++ b/youcat/src/main/webapp/openapi/vosi/vosi-table-ops-job-phase.yaml @@ -0,0 +1,55 @@ +get: + operationId: vosi-table-ops-job-phase-get + tags: + - VOSI Table Operations + summary: get a UWS job phase + description: job phase resource + parameters: + - name: jobID + in: path + description: unique job identifier generated by the server + required: true + type: string + example: a1b2c3 + responses: + '200': + description: the current phase + content: + text/plain: + schema: + type: string + example: "PENDING" + +post: + operationId: vosi-table-ops-job-phase-update + tags: + - VOSI Table Operations + summary: change a UWS job phase + description: update job + parameters: + - name: jobID + in: path + description: unique job identifier generated by the server + required: true + type: string + example: a1b2c3 + - name: PHASE + in: query + description: attempt to change the phase + required: true + schema: + type: string + enum: [ABORT, RUN] + example: RUN + responses: + '200': + description: phase change successful + '400': + $ref: ../uws/uws-responses.yaml#/invalid-phase-change + '401': + $ref: ../vosi/vosi-std-responses.yaml#/not-authenticated + '403': + $ref: ../vosi/vosi-std-responses.yaml#/permission-denied + '404': + $ref: ../vosi/vosi-std-responses.yaml#/not-found + diff --git a/youcat/src/main/webapp/openapi/vosi/vosi-table-ops-job.yaml b/youcat/src/main/webapp/openapi/vosi/vosi-table-ops-job.yaml new file mode 100644 index 00000000..f46065d8 --- /dev/null +++ b/youcat/src/main/webapp/openapi/vosi/vosi-table-ops-job.yaml @@ -0,0 +1,28 @@ +get: + operationId: vosi-table-ops-job-get + tags: + - VOSI Table Operations + summary: get a UWS job description + description: job resource + parameters: + - name: jobID + in: path + description: unique job identifier generated by the server + required: true + type: string + example: a1b2c3 + - name: WAIT + in: query + description: wait for the specified time in seconds or until the phase changes + required: false + type: integer + example: WAIT=60 + responses: + '200': + $ref: ../uws/uws-responses.yaml#/job + '401': + $ref: ../vosi/vosi-std-responses.yaml#/not-authenticated + '403': + $ref: ../vosi/vosi-std-responses.yaml#/permission-denied + '404': + $ref: ../vosi/vosi-std-responses.yaml#/not-found diff --git a/youcat/src/main/webapp/openapi/vosi/vosi-table-ops.yaml b/youcat/src/main/webapp/openapi/vosi/vosi-table-ops.yaml new file mode 100644 index 00000000..378d3cc2 --- /dev/null +++ b/youcat/src/main/webapp/openapi/vosi/vosi-table-ops.yaml @@ -0,0 +1,61 @@ +get: + operationId: vosi-table-ops-job-list + tags: + - VOSI Table Operations + summary: list async table update jobs + description: async job listing + parameters: + responses: + '200': + $ref: ../uws/uws-responses.yaml#/job-listing + '401': + $ref: ./vosi-std-responses.yaml#/not-authenticated + '403': + $ref: ./vosi-std-responses.yaml#/permission-denied +post: + operationId: vosi-table-ops-job-create + tags: + - VOSI Table Operations + summary: create async table update job + description: TAP asynchronous table update (create UWS Job) + parameters: + - name: table + in: query + description: a single table name as provided in tap_schema + required: true + schema: + type: string + - name: index + in: query + description: | + create index operation; value is a column name in the table + or a comma-separated list of columns + required: false + schema: + type: string + - name: itype + in: query + description: | + qualifier to create a specialised index: a value of long-lat + requires 2 numeric columns which are used as longitude,latitude + pairs (spherical coordinates); a value of x-y requires 2 numeric + columns which are used as x,y pairs (cartesian coordinates) + required: false + schema: + type: string + enum: [long-lat,x-y] + - name: unique + in: query + description: qualifier to create a unique index + required: false + schema: + type: boolean + responses: + '303': + $ref: ../uws/uws-responses.yaml#/created + '401': + $ref: ./vosi-std-responses.yaml#/not-authenticated + '403': + $ref: ./vosi-std-responses.yaml#/permission-denied + '404': + $ref: ./vosi-std-responses.yaml#/not-found From 076507c47c0bf2bbe76fe195a24251757cd0785b Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Wed, 1 Apr 2026 11:48:44 -0700 Subject: [PATCH 19/23] update documented table-ops endpoint to match current build sync latest VOSI openapi --- youcat/src/main/webapp/openapi.yaml | 7 ++++--- .../src/main/webapp/openapi/vosi/vosi-table-ops.yaml | 10 ++++++---- 2 files changed, 10 insertions(+), 7 deletions(-) diff --git a/youcat/src/main/webapp/openapi.yaml b/youcat/src/main/webapp/openapi.yaml index 44c40aa4..d603fd8e 100644 --- a/youcat/src/main/webapp/openapi.yaml +++ b/youcat/src/main/webapp/openapi.yaml @@ -71,11 +71,12 @@ paths: /tables/{name}: $ref: ./openapi/vosi/vosi-table.yaml - /table-ops: +# note use of /table-update rather than /table-ops from VOSI + /table-update: $ref: ./openapi/vosi/vosi-table-ops.yaml - /table-ops/{jobID}: + /table-update/{jobID}: $ref: ./openapi/vosi/vosi-table-ops-job.yaml - /table-ops/{jobID}/phase: + /table-update/{jobID}/phase: $ref: ./openapi/vosi/vosi-table-ops-job-phase.yaml /load/{name}: diff --git a/youcat/src/main/webapp/openapi/vosi/vosi-table-ops.yaml b/youcat/src/main/webapp/openapi/vosi/vosi-table-ops.yaml index 378d3cc2..c5734517 100644 --- a/youcat/src/main/webapp/openapi/vosi/vosi-table-ops.yaml +++ b/youcat/src/main/webapp/openapi/vosi/vosi-table-ops.yaml @@ -12,6 +12,8 @@ get: $ref: ./vosi-std-responses.yaml#/not-authenticated '403': $ref: ./vosi-std-responses.yaml#/permission-denied + '404': + $ref: ./vosi-std-responses.yaml#/not-found post: operationId: vosi-table-ops-job-create tags: @@ -19,13 +21,13 @@ post: summary: create async table update job description: TAP asynchronous table update (create UWS Job) parameters: - - name: table + - name: TABLE in: query description: a single table name as provided in tap_schema required: true schema: type: string - - name: index + - name: INDEX in: query description: | create index operation; value is a column name in the table @@ -33,7 +35,7 @@ post: required: false schema: type: string - - name: itype + - name: INDEX_TYPE in: query description: | qualifier to create a specialised index: a value of long-lat @@ -44,7 +46,7 @@ post: schema: type: string enum: [long-lat,x-y] - - name: unique + - name: UNIQUE in: query description: qualifier to create a unique index required: false From 8a651849b7fe9d68faf9df08a46cf28d5c1de7d7 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Thu, 9 Apr 2026 10:06:21 -0700 Subject: [PATCH 20/23] youcat: sync openapi from VOSI and TAP --- .../openapi/tap/tap-async-job-phase.yaml | 24 +++---------------- .../webapp/openapi/tap/tap-async-job.yaml | 14 ++--------- .../main/webapp/openapi/tap/tap-async.yaml | 3 +++ .../main/webapp/openapi/tap/tap-result.yaml | 7 +----- .../webapp/openapi/uws/uws-after-param.yaml | 8 +++++++ .../webapp/openapi/uws/uws-jobid-param.yaml | 7 ++++++ .../webapp/openapi/uws/uws-last-param.yaml | 11 +++++++++ .../openapi/uws/uws-phase-change-param.yaml | 8 +++++++ .../webapp/openapi/uws/uws-phase-param.yaml | 7 ++++++ .../webapp/openapi/uws/uws-responses.yaml | 2 +- .../webapp/openapi/uws/uws-wait-param.yaml | 8 +++++++ .../vosi/vosi-table-ops-job-phase.yaml | 23 +++--------------- .../openapi/vosi/vosi-table-ops-job.yaml | 14 ++--------- .../webapp/openapi/vosi/vosi-table-ops.yaml | 3 +++ 14 files changed, 67 insertions(+), 72 deletions(-) create mode 100644 youcat/src/main/webapp/openapi/uws/uws-after-param.yaml create mode 100644 youcat/src/main/webapp/openapi/uws/uws-jobid-param.yaml create mode 100644 youcat/src/main/webapp/openapi/uws/uws-last-param.yaml create mode 100644 youcat/src/main/webapp/openapi/uws/uws-phase-change-param.yaml create mode 100644 youcat/src/main/webapp/openapi/uws/uws-phase-param.yaml create mode 100644 youcat/src/main/webapp/openapi/uws/uws-wait-param.yaml diff --git a/youcat/src/main/webapp/openapi/tap/tap-async-job-phase.yaml b/youcat/src/main/webapp/openapi/tap/tap-async-job-phase.yaml index 3d9031a2..79ca646d 100644 --- a/youcat/src/main/webapp/openapi/tap/tap-async-job-phase.yaml +++ b/youcat/src/main/webapp/openapi/tap/tap-async-job-phase.yaml @@ -5,12 +5,7 @@ get: summary: get a UWS job phase description: job phase resource parameters: - - name: jobID - in: path - description: unique job identifier generated by the server - required: true - type: string - example: a1b2c3 + - $ref: ../uws/uws-jobid-param.yaml responses: '200': description: successful response @@ -26,21 +21,8 @@ post: summary: change a UWS job phase description: update job parameters: - - name: jobID - in: path - description: unique job identifier generated by the server - required: true - type: string - example: a1b2c3 - - name: PHASE - in: query - description: attempt to change the phase - required: true - schema: - type: string - enum: [ABORT, RUN] - example: RUN - + - $ref: ../uws/uws-jobid-param.yaml + - $ref: ../uws/uws-phase-change-param.yaml responses: '200': description: phase change successful diff --git a/youcat/src/main/webapp/openapi/tap/tap-async-job.yaml b/youcat/src/main/webapp/openapi/tap/tap-async-job.yaml index 1f7fb9cc..aeba4dea 100644 --- a/youcat/src/main/webapp/openapi/tap/tap-async-job.yaml +++ b/youcat/src/main/webapp/openapi/tap/tap-async-job.yaml @@ -5,18 +5,8 @@ get: summary: get a UWS job description description: job resource parameters: - - name: jobID - in: path - description: unique job identifier generated by the server - required: true - type: string - example: a1b2c3 - - name: WAIT - in: query - description: wait for the specified time in seconds or until the phase changes - required: false - type: integer - example: WAIT=60 + - $ref: ../uws/uws-jobid-param.yaml + - $ref: ../uws/uws-wait-param.yaml responses: '200': $ref: ../uws/uws-responses.yaml#/job diff --git a/youcat/src/main/webapp/openapi/tap/tap-async.yaml b/youcat/src/main/webapp/openapi/tap/tap-async.yaml index d42e0c97..78ccf602 100644 --- a/youcat/src/main/webapp/openapi/tap/tap-async.yaml +++ b/youcat/src/main/webapp/openapi/tap/tap-async.yaml @@ -5,6 +5,9 @@ get: summary: list queries (UWS jobs) description: TAP asynchronous query endpoint (list UWS Jobs) parameters: + - $ref: ../uws/uws-phase-param.yaml + - $ref: ../uws/uws-after-param.yaml + - $ref: ../uws/uws-last-param.yaml responses: '200': $ref: ../uws/uws-responses.yaml#/job-listing diff --git a/youcat/src/main/webapp/openapi/tap/tap-result.yaml b/youcat/src/main/webapp/openapi/tap/tap-result.yaml index b1cba58a..7b70047e 100644 --- a/youcat/src/main/webapp/openapi/tap/tap-result.yaml +++ b/youcat/src/main/webapp/openapi/tap/tap-result.yaml @@ -5,12 +5,7 @@ get: summary: async query result description: download async query result for a completed job parameters: - - name: jobID - in: path - description: unique job identifier generated by the server - required: true - type: string - example: a1b2c3 + - $ref: ../uws/uws-jobid-param.yaml responses: '200': $ref: '#/components/schemas/queryResult' diff --git a/youcat/src/main/webapp/openapi/uws/uws-after-param.yaml b/youcat/src/main/webapp/openapi/uws/uws-after-param.yaml new file mode 100644 index 00000000..c5afec81 --- /dev/null +++ b/youcat/src/main/webapp/openapi/uws/uws-after-param.yaml @@ -0,0 +1,8 @@ +name: AFTER +in: query +description: list jobs with creationTime after the specified value +required: false +schema: + type: string + format: date-time + example: "2017-07-21T17:32:28Z" diff --git a/youcat/src/main/webapp/openapi/uws/uws-jobid-param.yaml b/youcat/src/main/webapp/openapi/uws/uws-jobid-param.yaml new file mode 100644 index 00000000..2c03a07b --- /dev/null +++ b/youcat/src/main/webapp/openapi/uws/uws-jobid-param.yaml @@ -0,0 +1,7 @@ +name: jobID +in: path +description: unique job identifier generated by the server +required: true +schema: + type: string + example: a1b2c3 diff --git a/youcat/src/main/webapp/openapi/uws/uws-last-param.yaml b/youcat/src/main/webapp/openapi/uws/uws-last-param.yaml new file mode 100644 index 00000000..93a53b70 --- /dev/null +++ b/youcat/src/main/webapp/openapi/uws/uws-last-param.yaml @@ -0,0 +1,11 @@ +name: LAST +in: query +description: | + limit the number of jobs listed to the specified value; use of LAST + also causes the server to return jobs in order of creationTime (descending) + with the most recent jobs first +required: false +schema: + type: integer + minimum: 0 + example: 10 diff --git a/youcat/src/main/webapp/openapi/uws/uws-phase-change-param.yaml b/youcat/src/main/webapp/openapi/uws/uws-phase-change-param.yaml new file mode 100644 index 00000000..7a0f156a --- /dev/null +++ b/youcat/src/main/webapp/openapi/uws/uws-phase-change-param.yaml @@ -0,0 +1,8 @@ +name: PHASE +in: query +description: attempt to change the phase +required: true +schema: + type: string + enum: [ABORT, RUN] + example: RUN diff --git a/youcat/src/main/webapp/openapi/uws/uws-phase-param.yaml b/youcat/src/main/webapp/openapi/uws/uws-phase-param.yaml new file mode 100644 index 00000000..610991bd --- /dev/null +++ b/youcat/src/main/webapp/openapi/uws/uws-phase-param.yaml @@ -0,0 +1,7 @@ +name: PHASE +in: query +description: list jobs in this execution phase +required: false +schema: + type: string + example: "EXECUTING" diff --git a/youcat/src/main/webapp/openapi/uws/uws-responses.yaml b/youcat/src/main/webapp/openapi/uws/uws-responses.yaml index e4515cce..6fd58db5 100644 --- a/youcat/src/main/webapp/openapi/uws/uws-responses.yaml +++ b/youcat/src/main/webapp/openapi/uws/uws-responses.yaml @@ -31,7 +31,7 @@ job-listing: 2024-07-16T16:38:33.090Z ... - + job: description: a single UWS Job diff --git a/youcat/src/main/webapp/openapi/uws/uws-wait-param.yaml b/youcat/src/main/webapp/openapi/uws/uws-wait-param.yaml new file mode 100644 index 00000000..704166e3 --- /dev/null +++ b/youcat/src/main/webapp/openapi/uws/uws-wait-param.yaml @@ -0,0 +1,8 @@ +name: WAIT +in: query +description: wait for the specified time in seconds or until the phase changes +required: false +schema: + type: integer + example: WAIT=60 + diff --git a/youcat/src/main/webapp/openapi/vosi/vosi-table-ops-job-phase.yaml b/youcat/src/main/webapp/openapi/vosi/vosi-table-ops-job-phase.yaml index 83790608..5c382f9e 100644 --- a/youcat/src/main/webapp/openapi/vosi/vosi-table-ops-job-phase.yaml +++ b/youcat/src/main/webapp/openapi/vosi/vosi-table-ops-job-phase.yaml @@ -5,12 +5,7 @@ get: summary: get a UWS job phase description: job phase resource parameters: - - name: jobID - in: path - description: unique job identifier generated by the server - required: true - type: string - example: a1b2c3 + - $ref: ../uws/uws-jobid-param.yaml responses: '200': description: the current phase @@ -27,20 +22,8 @@ post: summary: change a UWS job phase description: update job parameters: - - name: jobID - in: path - description: unique job identifier generated by the server - required: true - type: string - example: a1b2c3 - - name: PHASE - in: query - description: attempt to change the phase - required: true - schema: - type: string - enum: [ABORT, RUN] - example: RUN + - $ref: ../uws/uws-jobid-param.yaml + - $ref: ../uws/uws-phase-change-param.yaml responses: '200': description: phase change successful diff --git a/youcat/src/main/webapp/openapi/vosi/vosi-table-ops-job.yaml b/youcat/src/main/webapp/openapi/vosi/vosi-table-ops-job.yaml index f46065d8..fb12a57a 100644 --- a/youcat/src/main/webapp/openapi/vosi/vosi-table-ops-job.yaml +++ b/youcat/src/main/webapp/openapi/vosi/vosi-table-ops-job.yaml @@ -5,18 +5,8 @@ get: summary: get a UWS job description description: job resource parameters: - - name: jobID - in: path - description: unique job identifier generated by the server - required: true - type: string - example: a1b2c3 - - name: WAIT - in: query - description: wait for the specified time in seconds or until the phase changes - required: false - type: integer - example: WAIT=60 + - $ref: ../uws/uws-jobid-param.yaml + - $ref: ../uws/uws-wait-param.yaml responses: '200': $ref: ../uws/uws-responses.yaml#/job diff --git a/youcat/src/main/webapp/openapi/vosi/vosi-table-ops.yaml b/youcat/src/main/webapp/openapi/vosi/vosi-table-ops.yaml index c5734517..413972be 100644 --- a/youcat/src/main/webapp/openapi/vosi/vosi-table-ops.yaml +++ b/youcat/src/main/webapp/openapi/vosi/vosi-table-ops.yaml @@ -5,6 +5,9 @@ get: summary: list async table update jobs description: async job listing parameters: + - $ref: ../uws/uws-phase-param.yaml + - $ref: ../uws/uws-after-param.yaml + - $ref: ../uws/uws-last-param.yaml responses: '200': $ref: ../uws/uws-responses.yaml#/job-listing From 145a4ec891efdb0fa5a4b9cebb3dea1fcd4c6d5a Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Thu, 9 Apr 2026 10:09:37 -0700 Subject: [PATCH 21/23] change rsync to pull UWS from VOSI repo --- youcat/rsync-openapi-components.sh | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/youcat/rsync-openapi-components.sh b/youcat/rsync-openapi-components.sh index 1fcf4198..9156ca93 100755 --- a/youcat/rsync-openapi-components.sh +++ b/youcat/rsync-openapi-components.sh @@ -7,7 +7,8 @@ TAP=$HOME/work/dev/ivoa-std/TAP.git ARGS="$1 -avc --delete" rsync $ARGS $VOSI/openapi/vosi src/main/webapp/openapi/ +rsync $ARGS $VOSI/openapi/uws src/main/webapp/openapi/ + rsync $ARGS $DALI/openapi/dali src/main/webapp/openapi/ -rsync $ARGS $TAP/openapi/uws src/main/webapp/openapi/ rsync $ARGS $TAP/openapi/tap src/main/webapp/openapi/ From e3566479e0c0c0c6e861ded884ab5bf4934ea236 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Tue, 28 Apr 2026 15:25:18 -0700 Subject: [PATCH 22/23] youcat: deliver OpenAPI docs appropriate to the config if an admin is configured, deliver complete youcat docs if admin not configured, deliver TAP-1.1 compatible docs --- .../org/opencadc/youcat/YoucatInitAction.java | 27 ++++++ youcat/src/main/webapp/openapi-base.yaml | 41 ++++++++ .../{openapi.yaml => openapi-youcat.yaml} | 11 +-- .../webapp/openapi/vosi/vosi-table-11.yaml | 94 +++++++++++++++++++ 4 files changed, 167 insertions(+), 6 deletions(-) create mode 100644 youcat/src/main/webapp/openapi-base.yaml rename youcat/src/main/webapp/{openapi.yaml => openapi-youcat.yaml} (85%) create mode 100644 youcat/src/main/webapp/openapi/vosi/vosi-table-11.yaml diff --git a/youcat/src/main/java/org/opencadc/youcat/YoucatInitAction.java b/youcat/src/main/java/org/opencadc/youcat/YoucatInitAction.java index dd103a40..0f09caf9 100644 --- a/youcat/src/main/java/org/opencadc/youcat/YoucatInitAction.java +++ b/youcat/src/main/java/org/opencadc/youcat/YoucatInitAction.java @@ -80,6 +80,10 @@ import ca.nrc.cadc.uws.server.impl.InitDatabaseUWS; import ca.nrc.cadc.vosi.actions.DeleteAction; import ca.nrc.cadc.vosi.actions.TablesAction; +import java.net.URL; +import java.nio.file.Files; +import java.nio.file.Path; +import java.nio.file.StandardCopyOption; import javax.naming.Context; import javax.naming.InitialContext; import javax.security.auth.Subject; @@ -106,6 +110,8 @@ public class YoucatInitAction extends InitAction { private String defaultVOTableSerialization = null; private String deletedSchemaName = null; + private boolean adminConfigured = false; + public YoucatInitAction() { } @@ -124,10 +130,12 @@ private void initConfig() { sb.append("\n\t").append(YOUCAT_ADMIN).append(": "); if (adminUserStr == null) { sb.append("MISSING"); + this.adminConfigured = false; } else { try { IdentityManager im = AuthenticationUtil.getIdentityManager(); admin = im.toSubject(adminUserStr); + this.adminConfigured = true; String str = admin.toString().replaceAll("\n", " "); sb.append(str).append(" OK"); } catch (Exception ex) { @@ -223,6 +231,25 @@ public void doInit() { DefaultTableWriter.setDefaultVOTableSerialization(defaultVOTableSerialization); DeleteAction.setDeletedSchemaName(deletedSchemaName); + initOpenApiDocs(); + } catch (Exception ex) { + throw new RuntimeException("INIT FAIL: " + ex.getMessage(), ex); + } + } + + private void initOpenApiDocs() { + try { + URL resURL = super.getResource("openapi-base.yaml"); + if (adminConfigured) { + resURL = super.getResource("openapi-youcat.yaml"); + } + + String path = resURL.getPath(); + log.warn("found openapi: " + resURL + " at " + path); + Path src = Path.of(resURL.toURI()); + Path dest = src.getParent().resolve("openapi.yaml"); + Files.copy(src, dest, StandardCopyOption.COPY_ATTRIBUTES); + log.warn("copy: " + src + " -> " + dest); } catch (Exception ex) { throw new RuntimeException("INIT FAIL: " + ex.getMessage(), ex); } diff --git a/youcat/src/main/webapp/openapi-base.yaml b/youcat/src/main/webapp/openapi-base.yaml new file mode 100644 index 00000000..b7cc6bce --- /dev/null +++ b/youcat/src/main/webapp/openapi-base.yaml @@ -0,0 +1,41 @@ +openapi: 3.1.0 +info: + title: | + TAP: generic OpenCADC TAP service implementation + version: "0.9.4" + description: | + This service implements the WD-TAP-1.2 API specification with components imported from + VOSI, UWS, and DALI. Querying is completely compatible with the IVOA TAP-1.1 Recommendation. + + This service is configured for basic TAP operation only. While the service implements + the complete standard, the UWS job child paths described below are a subset. + +servers: +- url: /youcat + +tags: + - name: TAP Query + - name: VOSI Capabilities + - name: VOSI Table Metadata + +paths: + /sync: + $ref: ./openapi/tap/tap-sync.yaml + /async: + $ref: ./openapi/tap/tap-async.yaml + /async/{jobID}: + $ref: ./openapi/tap/tap-async-job.yaml + /async/{jobID}/phase: + $ref: ./openapi/tap/tap-async-job-phase.yaml + /async/{jobID}/results/result: + $ref: ./openapi/tap/tap-result.yaml + + /capabilities: + $ref: ./openapi/vosi/vosi-capabilities.yaml + + /tables: + $ref: ./openapi/vosi/vosi-tableset.yaml + /tables/{name}: + $ref: ./openapi/vosi/vosi-table-11.yaml + + diff --git a/youcat/src/main/webapp/openapi.yaml b/youcat/src/main/webapp/openapi-youcat.yaml similarity index 85% rename from youcat/src/main/webapp/openapi.yaml rename to youcat/src/main/webapp/openapi-youcat.yaml index d603fd8e..d865c6c5 100644 --- a/youcat/src/main/webapp/openapi.yaml +++ b/youcat/src/main/webapp/openapi-youcat.yaml @@ -1,16 +1,15 @@ openapi: 3.1.0 info: title: | - YouCat: a TAP service with user-owned and created tables. + youcat: an OpenCADC TAP service with support for user-owned and managed tables version: "0.9.2" description: | This service implements the WD-TAP-1.2 API specification with components imported from - VOSI, UWS, and DALI. Querying is completely compatible with the - TAP-1.1 Recommendation. + VOSI, UWS, and DALI. Querying is completely compatible with the IVOA TAP-1.1 Recommendation. - YouCat supports user management of permissions at both the schema and table level. A schema - owner is set when a YouCat allocation is created by the service operator. A table owner is - the user who created the table. Owners can set a flag for anonymous reading and can set + The youcat service supports user management of permissions at both the schema and table level. + A schema owner is set when a YouCat allocation is created by the service operator. A table owner + is the user who created the table. Owners can set a flag for anonymous reading and can set groups for read-only and read-write permissons. The following describes the three types of grants: diff --git a/youcat/src/main/webapp/openapi/vosi/vosi-table-11.yaml b/youcat/src/main/webapp/openapi/vosi/vosi-table-11.yaml new file mode 100644 index 00000000..21fb3043 --- /dev/null +++ b/youcat/src/main/webapp/openapi/vosi/vosi-table-11.yaml @@ -0,0 +1,94 @@ +# this is the read-only /tables/{tableName} endpoint from VOSI-1.1 +get: + operationId: read-table-metadata + tags: + - VOSI Table Metadata + summary: get metadata for the specified table + description: provides the table metadata for a single schema or table + parameters: + - in: path + name: name + description: a single schema name or table name as provided in tap_schema + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/schemas/tableDoc' + '401': + $ref: ./vosi-std-responses.yaml#/not-authenticated + '403': + $ref: ./vosi-std-responses.yaml#/permission-denied + '404': + $ref: ./vosi-std-responses.yaml#/not-found + +components: + schemas: + tableDoc: + description: metadata for the specified schema or table + content: + text/xml: + schema: + type: object + xml: + name: table + prefix: vosi + namespace: http://www.ivoa.net/xml/VOSITables/v1.0 + example: | + + tap_schema.schemas + description of schemas in this tableset + + schema_name + schema name for reference to tap_schema.schemas + char + indexed + + + utype + lists the utypes of schemas in the tableset + char + + + description + describes schemas in the tableset + char + + + schema_index + recommended sort order when listing schemas + int + + + + application/x-votable+xml: + schema: + type: object + xml: + name: VOTABLE + namespace: http://www.ivoa.net/xml/VOTable/v1.3 + example: | + + + + + schema name for reference to tap_schema.schemas + + + lists the utypes of schemas in the tableset + + + describes schemas in the tableset + + + recommended sort order when listing schemas + + +
+ + + From 38ad2101e59b3c40c6f8fd91b47da47ce3e12ace Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Wed, 6 May 2026 13:04:42 -0700 Subject: [PATCH 23/23] update openapi components from upstream document some as yet unimplemented features in the openapi docs --- .../main/webapp/openapi/dali/dali-maxrec.yaml | 7 +++-- .../openapi/dali/dali-responseformat.yaml | 4 +++ .../main/webapp/openapi/dali/dali-upload.yaml | 11 ++++++-- .../webapp/openapi/uws/uws-wait-param.yaml | 2 +- .../webapp/openapi/vosi/vosi-table-ops.yaml | 27 ++++++++++--------- 5 files changed, 33 insertions(+), 18 deletions(-) diff --git a/youcat/src/main/webapp/openapi/dali/dali-maxrec.yaml b/youcat/src/main/webapp/openapi/dali/dali-maxrec.yaml index 42d5ac76..920b2189 100644 --- a/youcat/src/main/webapp/openapi/dali/dali-maxrec.yaml +++ b/youcat/src/main/webapp/openapi/dali/dali-maxrec.yaml @@ -2,8 +2,11 @@ name: MAXREC in: query description: | request a specific limit on number of records to return +required: false schema: type: integer format: int64 - minimum: 0 - exclusiveMinimum: false + inclusiveMinimum: 0 + examples: + - 0 + - 100 diff --git a/youcat/src/main/webapp/openapi/dali/dali-responseformat.yaml b/youcat/src/main/webapp/openapi/dali/dali-responseformat.yaml index 202eee4c..8b3e4042 100644 --- a/youcat/src/main/webapp/openapi/dali/dali-responseformat.yaml +++ b/youcat/src/main/webapp/openapi/dali/dali-responseformat.yaml @@ -1,5 +1,9 @@ name: RESPONSEFORMAT in: query description: select output table format +required: false schema: type: string + examples: + - application/x-votable+xml + - vot diff --git a/youcat/src/main/webapp/openapi/dali/dali-upload.yaml b/youcat/src/main/webapp/openapi/dali/dali-upload.yaml index ef9f0185..3b5fbdd2 100644 --- a/youcat/src/main/webapp/openapi/dali/dali-upload.yaml +++ b/youcat/src/main/webapp/openapi/dali/dali-upload.yaml @@ -3,6 +3,13 @@ in: query description: | specify a comma-separated name,location pair for a temporary resource to be uploaded and used in the request +required: false +explode: true schema: - type: string - pattern: '^[a-zA-Z]\w*,\S+$' + type: array + items: + type: string + pattern: '^[a-zA-Z]\w*,\S+$' + example: + - tmp1,https://example.net/tmp.vot + - tmp2,param:inline-votable diff --git a/youcat/src/main/webapp/openapi/uws/uws-wait-param.yaml b/youcat/src/main/webapp/openapi/uws/uws-wait-param.yaml index 704166e3..31fadab3 100644 --- a/youcat/src/main/webapp/openapi/uws/uws-wait-param.yaml +++ b/youcat/src/main/webapp/openapi/uws/uws-wait-param.yaml @@ -4,5 +4,5 @@ description: wait for the specified time in seconds or until the phase changes required: false schema: type: integer - example: WAIT=60 + example: 60 diff --git a/youcat/src/main/webapp/openapi/vosi/vosi-table-ops.yaml b/youcat/src/main/webapp/openapi/vosi/vosi-table-ops.yaml index 413972be..f54bee8f 100644 --- a/youcat/src/main/webapp/openapi/vosi/vosi-table-ops.yaml +++ b/youcat/src/main/webapp/openapi/vosi/vosi-table-ops.yaml @@ -28,33 +28,34 @@ post: in: query description: a single table name as provided in tap_schema required: true + explode: false schema: type: string - name: INDEX in: query description: | create index operation; value is a column name in the table - or a comma-separated list of columns - required: false + or (NOT IMPLEMENTED) a comma-separated list of columns; order matters + required: true schema: - type: string + type: string + #pattern: ?? - name: INDEX_TYPE in: query description: | - qualifier to create a specialised index: a value of long-lat + NOT IMPLEMENTED: qualifier to create a specialised index: a value of long-lat requires 2 numeric columns which are used as longitude,latitude pairs (spherical coordinates); a value of x-y requires 2 numeric - columns which are used as x,y pairs (cartesian coordinates) + columns which are used as x,y pairs (cartesian coordinates); required: false + # style: form (default), explode: true, and type: array + # means the normal zero or more param=value + explode: true schema: - type: string - enum: [long-lat,x-y] - - name: UNIQUE - in: query - description: qualifier to create a unique index - required: false - schema: - type: boolean + type: array + items: + type: string + enum: [long-lat,x-y,unique] responses: '303': $ref: ../uws/uws-responses.yaml#/created