add external platforms

carmin.yaml

@@ -180,7 +180,10 @@ paths:
           $ref: '#/components/responses/Error'
   /executions/{executionIdentifier}/results:
     get:
-      summary: Get the result files of the execution
+      summary: Get information about the results files
+      description: |
+        Only the files stored on this platform must be listed, so it must not include the files that were transfered to external platforms.
+        The path objects that are returned are meant to be used with the methods of the data module in order to download the results files.
       operationId: getExecutionResults
       parameters:
       - $ref: '#/components/parameters/PathExecutionIdentifier'
@@ -250,7 +253,7 @@ paths:
   /pipelines:
     get:
       summary: List pipelines
-      description: >
+      description: |
         If an user is identified, the platform must return all the pipelines this user can execute, and it may also return additional pipelines that the user cannot execute.
         This method can also be used without being identified, in a anonymous way, with the objective of advertising. In the case, the platform may return any number of pipelines and all of them must have the "canExecute" property set to false. A platform can ignore this feature by returning an empty list.
 
@@ -376,7 +379,7 @@ paths:
           $ref: '#/components/responses/Error'
     put:
       summary: Upload data to a path
-      description: >
+      description: |
         The parent directory of the given path must exist.
 
         A request without content creates a directory (an error should be returned if the path already exists).
@@ -445,6 +448,78 @@ paths:
           description: the deletion is successful and finished.
         default:
           $ref: '#/components/responses/Error'
+  /externalPlatforms:
+    get:
+      summary: Lists all the supported external platforms
+      operationId: listExternalPlatforms
+      description:
+        This method lists all the external platforms supported.
+        These platforms can be used as the sources for execution input, or as destinations for outputs.
+        A user must configure his credentials for an external platform he wants to use.
+      parameters: []
+      responses:
+        '200':
+          description: Succesful response.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/ExternalPlatform'
+        default:
+          $ref: '#/components/responses/Error'
+  /user/externalKeys:
+    get:
+      summary: Lists the external API keys of the current user
+      operationId: listExternalKeys
+      description:
+        To use external platform in execution inputs and output, a user need to configure his credentials to these external platforms.
+        This method lists the external API keys he has configured.
+        To add them, he has to use the addExternalKey method
+      parameters: []
+      responses:
+        '200':
+          description: successful response
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/ExternalKey'
+        default:
+          $ref: '#/components/responses/Error'
+    put:
+      summary: Configure an API key to an external platform
+      operationId : addExternalKey
+      description: Add or change the API key of the current user to a particular external platform.
+      parameters: []
+      requestBody:
+        content:
+          application/carmin+json:
+            schema:
+              $ref: '#/components/schemas/ExternalKey'
+      responses:
+        '204':
+          description: successful operation
+        default:
+          $ref: '#/components/responses/Error'
+  /user/externalKeys/{platformIdentifier}:
+    delete:
+      summary: Delete an API key to an external platform
+      operationId: deleteExternalKey
+      description: Delete the current user API key to the platform whose identifier is the one given on the path
+      parameters:
+      - name: platformIdentifier
+        in: path
+        required: true
+        schema:
+          type: string
+          format: ascii
+      responses:
+        '204':
+          description: successful operation
+        default:
+          $ref: '#/components/responses/Error'
 components:
   securitySchemes:
     ApiKey:
@@ -655,20 +730,43 @@ components:
         inputValues:
           type: object
           additionalProperties: true
-          description:
+          description: |
             Represents the input as a key/value object. The types should respect the parameters of the pipeline used for the execution.
-        returnedFiles:
+
+            When the type is "File", there are 2 possibilities :
+
+            1. If the desired file is on the same platform, it must be given as a complete path, for instance "/path/to/my/file".
+            2. If the desired file is on an external platform, it must be given as a complete path, prefixed with the platform identifier and a colon.
+
+            For instance "platformId:/path/to/file". The user must have a configured API key for this platform.
+        resultsLocation:
+          type: string
+          description: |
+            An optional path that specifies where the results should be put.
+
+            The format is the same as the one used for an input of type "File" in the "inputValues" property.
+            As in an input value, it is possible to specify a path from an external platform ;
+            In this case, the user must have a configured API key to the desired platform.
+
+            Whether it's on the local or an external platform, this path must corresponds to an existing folder.
+            If not, the execution may start anyway but should produce an error.
+        returnedValues:
           type: object
           additionalProperties:
-            type: array
-            items:
-              type: string
-              format: url
+            nullable: true
           readOnly: true
-          description:
-            Absent when not available (e.g. execution still running). Empty if no returned file is produced.
-            Each key/value of the "returnedFiles" object corresponds to an output pipeline parameter (with "isReturnedValue" set to true) and the key must be the parameter name. The value must be an array of valid URL strings.
-            A value array can be empty if the output parameter produces no value. It can have several URLs entries when the output is a directory with several files, a big file split in several download links, several files or any other implementation specific design.
+          description: |
+            Absent when not available (e.g. execution still running). Empty if there is no output parameter in the pipeline used.
+
+            Each key/value of this object must correspond to an output pipeline parameter (with "isReturnedValue" set to true) and the key string must be the parameter name.
+
+            The value can be null for an optional output parameter.
+            If there is a result, the value content depends of the output parameter type :
+
+            - if it is of type "List", then the value must be an array.
+            - if it is of type "File" and the platform does not support the data module, then it must be a string with the url format, or an array of strings with the url format.
+            - if it is of type "File" and the platform supports the data module, then it must be a string with the path format (including an optional platform prefix like "platformId:"), or an array of strings with this same path format.
+            - Otherwise the value must be of the corresponding json type (string, number, integer or boolean), or an array where all the elements have the corresponding json type.
         studyIdentifier:
           type: string
           format: ascii
@@ -791,3 +889,35 @@ components:
        from:
         type: string
         description: A string containing a JSON Pointer value.
+    ExternalPlatform:
+      type: object
+      required:
+      - identifier
+      - description
+      properties:
+        identifier:
+          type: string
+          format: ascii
+        url:
+          type: string
+          format: url
+          description: link to the public home page of the external platform (if it has one)
+        description:
+          type: string
+          description: description of the external platform
+    ExternalKey:
+      type: object
+      required:
+      - platformIdentifier
+      - APIKey
+      properties:
+        platformIdentifier:
+          type: string
+          format: ascii
+          description :
+            The identifier of the external platform this API key gives access to.
+            It must be an identifier of an existing external platform listed in the listExternalPlatforms method.
+        APIKey:
+          type: string
+          description:
+            the API key that identify the user on the external platform.