update table-ops openapi spec to include INDEX_TYPE

add table-ops job and phase using UWS pattern

Author: pdowler

openapi.yaml

@@ -9,6 +9,7 @@ servers:
 tags:
     - name: VOSI Capabilities
     - name: VOSI Table Metadata
+    - name: VOSI Table Operations
 
 paths:
 # notes: this is how another service like TAP would include VOSI endpoints using 
@@ -19,6 +20,14 @@ paths:
     /tables/{name}:
         $ref: ./openapi/vosi/vosi-table.yaml
         #$ref: https://ivoa.net/std/VOSI/vosi-table.yaml
+
     /capabilities:
         $ref: ./openapi/vosi/vosi-capabilities.yaml
         #$ref: https://ivoa.net/std/VOSI/vosi-capabilities.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

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
+

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

openapi/vosi/vosi-table-ops.yaml

@@ -1,21 +1,23 @@
 get:
-    operationId: table-ops-job-list
+    operationId: vosi-table-ops-job-list
     tags:
-      - Table Operations
+      - VOSI Table Operations
     summary: list async table update jobs
     description: async job listing
     parameters:
     responses:
-        200:
+        '200':
             $ref: ../uws/uws-responses.yaml#/job-listing
-        401:
+        '401':
             $ref: ./vosi-std-responses.yaml#/not-authenticated
-        403:
+        '403':
             $ref: ./vosi-std-responses.yaml#/permission-denied
+        '404':
+            $ref: ./vosi-std-responses.yaml#/not-found
 post:
-    operationId: table-ops-job-create
+    operationId: vosi-table-ops-job-create
     tags:
-      - Table Operations
+      - VOSI Table Operations
     summary: create async table update job 
     description: TAP asynchronous table update (create UWS Job)
     parameters:
@@ -27,22 +29,35 @@ post:
               type: string
         - name: INDEX
           in: query
-          description: create index operation; value is a column name in the table
+          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: INDEX_TYPE
+          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 for INDEX to create a unique index
+          description: qualifier to create a unique index
           required: false
           schema:
               type: boolean
     responses:
-        303:
+        '303':
             $ref: ../uws/uws-responses.yaml#/created
-        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