carmin.yaml

openapi: '3.0.0'
info:
  version: '0.3.1'
  title: CARMIN - Common API for Research Medical Imaging Network
  description: REST API for exchanging data and remotely calling pipelines.
  license:
    name: MIT License
    url: https://opensource.org/licenses/MIT
  contact:
    name: CARMIN mailing list
    url: https://groups.google.com/d/forum/carmin
    email: carmin@googlegroups.com
security: 
- ApiKey: []
paths:
  /platform:
    get:
      summary: Return information about the platform
      operationId: getPlatformProperties
      security: []
      responses:
        '200':
          description: successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformProperties'
        default:
          $ref: '#/components/responses/Error'
  /authenticate:
    post:
      summary: Return the API key necessary to use the API.
      description:
         The key can be dynamic (a new one for each request) or static (always the same one until the user change it in a back-end)
      operationId: authenticate
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthenticationCredentials'
      responses:
        '200':
          description: successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Authentication'
        default:
            $ref: '#/components/responses/Error'
  /executions:
    get:
      summary: List some executions.
      description:
        List all execution Ids in the platform which are ordered in decreasing submission time.
        All the executions that were launched by the user must be returned. It is up to the platform to return executions that the user did not launch.
        Return the executions with indexes ranging from offset to offset+limit-1.
        When studyIdentifier is present, all the executions that the user launched in the study must be returned.
      operationId: listExecutions
      parameters:
      - name: studyIdentifier
        description: When present, all the executions the user launched for this study must be returned
        in: query
        schema:
          type: string
      - name: offset
        description: Index of the first execution to be returned. Defaults to 0.
        in: query
        schema:
          type: string
      - name: limit
        description:
          Maximum number of exeuctions to be returned.
          Defaults to the "defaultLimitListExecutions" property in the getPlatformProperties method if present, to 500 otherwise.
        in: query
        schema:
          type: string
      responses:
        '200':
          description: successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Execution'
        default:
          $ref: '#/components/responses/Error'
    post:
      summary: Initialize an execution
      description:
        The successful response must contain the execution identifier. 
        If the status “Initializing” is returned, playExecution must be called to start the execution.
      operationId: createExecution
      requestBody :
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Execution'
      responses:
        '200':
          description: successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Execution'
        default:
          $ref: '#/components/responses/Error'
  /executions/count:
    get:
      summary: Get the number of the user's executions
      operationId: countExecutions
      parameters:
      - name: studyIdentifier
        in: query
        schema:
          type: string
      responses:
        '200':
          description: successful response
          content:
            text/plain:
              schema:
                type: integer
        default:
          $ref: '#/components/responses/Error'
  /executions/{executionIdentifier}:
    parameters:
    - $ref: '#/components/parameters/PathExecutionIdentifier'
    get:
      summary: Get information about an execution
      operationId: getExecution
      responses:
        '200':
          description: successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Execution'
        default:
          $ref: '#/components/responses/Error'
    put:
      summary: Modify an execution.
      description:
        Only the name and the timeout of the execution can be modified. 
        Changes to the identifier or the status will raise errors. 
        Changes to the other properties will be ignored.
      operationId: updateExecution
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Execution'
      responses:
        '204':
          description: successful response
        default:
          $ref: '#/components/responses/Error'
    delete:
      summary: Delete an execution
      description:
        This will kill the underlying processes (if possible) and free all resources associated with this execution (if deleteFiles parameter is present and true)
      operationId: deleteExecution
      parameters:
        - name: deleteFiles
          in: query
          schema:
            type: boolean
          description: Also delete all the associated resources (especially the output files).
      responses:
        '204':
          description: successful response
        default:
          $ref: '#/components/responses/Error'
  /executions/{executionIdentifier}/results:
    get:
      summary: Get the result files of the execution
      operationId: getExecutionResults
      parameters:
      - $ref: '#/components/parameters/PathExecutionIdentifier'
      responses:
        '200':
          description: successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Path'
        default:
          $ref: '#/components/responses/Error'
  /executions/{executionIdentifier}/stdout:
    get:
      summary: Get stdout of an execution
      operationId: getStdout
      parameters:
      - $ref: '#/components/parameters/PathExecutionIdentifier'
      responses:
        '200':
          description: successful response
          content:
            text/plain:
              schema:
                type: string
        default:
          $ref: '#/components/responses/Error'
  /executions/{executionIdentifier}/stderr:
    get:
      summary: Get stderr of an execution
      operationId: getStderr
      parameters:
      - $ref: '#/components/parameters/PathExecutionIdentifier'
      responses:
        '200':
          description: successful response
          content:
            text/plain:
              schema:
                type: string
        default:
          $ref: '#/components/responses/Error'
  /executions/{executionIdentifier}/play:
    put:
      summary: Play an execution
      operationId: playExecution
      parameters:
      - $ref: '#/components/parameters/PathExecutionIdentifier'
      responses:
        '204':
          description: successful response
        default:
          $ref: '#/components/responses/Error'
  /executions/{executionIdentifier}/kill:
    put:
      summary: Kill an execution
      operationId: killExecution
      parameters:
      - $ref: '#/components/parameters/PathExecutionIdentifier'
      responses:
        '204':
          description: successful response
        default:
          $ref: '#/components/responses/Error'
  /pipelines:
    get:
      summary: List pipelines
      description:
        All the pipelines that the user can execute must be returned.
        It is up to the platform to return pipelines that the user cannot execute.
        When studyIdentifier is present, all the pipelines that the user can execute in the study must be returned. In this case, execution rights denote the rights to execute the pipeline in the study.
      operationId: listPipelines
      parameters:
      - name: studyIdentifier
        in: query
        schema:
          type: string
          format: ascii
      - name: property
        in: query
        schema:
          type: string
        description: A pipeline property to filter the returned pipelines. It must listed in the "supportedPipelineProperties" of the getPlatformProperties method. All the returned pipelines must have this property set. Use also the "propertyValue" to filter on this property value.
      - name: propertyValue
        in: query
        schema:
          type: string
        description: A property value on which to filter the returned pipelines. The "property" parameter must also be present. All the returned pipelines must have this property equal to the value given in this parameter.
      responses:
        '200':
          description: successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pipeline'
        default:
          $ref: '#/components/responses/Error'
  /pipelines/{pipelineIdentifier}:
    get:
      summary: Show the definition of a pipeline
      operationId: getPipeline
      parameters:
      - name: pipelineIdentifier
        in: path
        required: true
        schema:
          type: string
          format: ascii
      responses:
        '200':
          description: successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pipeline'
        default: 
          $ref: '#/components/responses/Error'
  /pipelines/{pipelineIdentifier}/boutiquesdescriptor:
    get:
      summary: Returns the Boutiques descriptor of the pipeline, if available. 
      operationId: getBoutiquesDescriptor
      parameters:
      - name: pipelineIdentifier
        in: path
        required: true
        schema:
          type: string
          format: ascii
      responses:
        '200':
          description: successful response
          content:
            application/json:
              schema:
                $ref: 'http://raw.githubusercontent.com/boutiques/boutiques/0.5.8/tools/python/boutiques/schema/descriptor.schema.json'
        default: 
          $ref: '#/components/responses/Error'
  /path/{completePath}:
    get:
      summary: Get content or information for a given path
      description:
        Download a file (or a directory) or retun information about a specific path.
        The response format and content depends on the mandatory action query parameter (see the parameter description).
        Basically, the "content" action downloads the raw file, and the other actions return various information in a JSON record.
      operationId: getPath
      parameters:
      - name: completePath
        in: path
        required: true
        description: the complete path on which to request information. 
          It can contain non-encoded slashes. 
          Except for the "exists" action, any request on a non-existing path should return an error
        schema:
          type: string
      - name: action
        in: query
        required: true
        description:
          The "content" action downloads the raw file. If the path points to a directory, a tarball of this directory is returned. 
          The "exists" action returns a BooleanResponse object (see definition) indicating if the path exists or not. 
          The "properties" action returns a Path object (see definition) with the path properties. 
          The "list" action returns a DirectoryList object (see definition) with the properties of all the files of the directory (if the path is not a directory an error must be returned). 
          The "md5" action is optional and returns a PathMd5 object (see definition).
        schema:
          type: string  
          enum:
          - content
          - exists
          - properties
          - list
          - md5
      responses:
        '200':
          description: successful response. 
            If the action is "content", the raw file (or a tarball) is returned, with the according mime type. 
            Otherwise a json response a returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPathResponse' 
            application/octet-stream:
              # any media type is accepted, equivalent to `*/*`
              schema:
                type: string
                format: binary
        default:
          $ref: '#/components/responses/Error'
    put:
      summary: Upload data to a path
      description:
        A request without content creates a directory (an error should be returned if the path already exists).
        A request with a specific content type ("application/carmin+json") allows to upload data encoded in base64.
        The base64 content (part of a json payload) can either be an encoded file, are an encoded zip archive that will create a directory.
        All other content (with any content type) will be considered as a raw file and will override the existing path content.
        If the parent directory of the file/directory to create does not exist, an error must be returned.
      operationId: uploadPath
      parameters:
      - name: completePath
        in: path
        required: true
        description:
          The complete path on which to upload data.
          It can contain non-encoded slashes.
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/carmin+json:
            schema:
              $ref: '#/components/schemas/UploadData'
          application/octet-stream:
            # any media type is accepted, equivalent to `*/*`
            schema:
              type: string
              format: binary
      responses:
        '201':
          description: The upload is successful and finished.
          headers:
            Location:
              description: The url to access the created or updated path
              schema:
                type: string
                format: url
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Path' 
        default:
          $ref: '#/components/responses/Error'
    delete:
      summary: Delete a path
      description:
        Delete a path and transitively delete all its content if it is a directory.
      operationId: DeletePath
      parameters:
      - name: completePath
        in: path
        required: true
        description:
          The complete path to delete.
          It can contain non-encoded slashes.
        schema:
          type: string
      responses:
        '204':
          description: the deletion is successful and finished.
        default:
          $ref: '#/components/responses/Error'
components:
  securitySchemes:
    ApiKey:
      type: apiKey
      name: apikey
      in: header
      description: An API key that must be provided by the platform.
  parameters:
    PathExecutionIdentifier:
      name: executionIdentifier
      in: path
      required: true   
      schema:
        type: string
        format: ascii
  responses:
    Error:
      description: A functional or internal error occured processing the request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorCodeAndMessage'
  schemas:
    ErrorCodeAndMessage:
      type: object
      required:
        - errorCode
        - errorMessage
      properties:
        errorCode:
          type: integer
          format: int64
        errorMessage:
          type: string
        errorDetails:
          description: optional pieces of information about the error(s)
          type: object
          additionalProperties: true
    PlatformProperties:
      type: object
      required:
        - supportedModules
        - supportedAPIVersion
      properties:
        platformName: # not present in 0.2 version, keep it as optional
          type: string
          description: Name of the platform.
        APIErrorCodesAndMessages:
          type: array
          items:
            $ref: '#/components/schemas/ErrorCodeAndMessage'
        supportedModules:
          type: array
          items:
            type: string
            enum: ["Processing", "Data", "AdvancedData", "Management", "Commercial", ]
        defaultLimitListExecutions: # not present in 0.2, keep it as optional
          type: integer
          format: int64
          description: The number of Executions returned by getExecutions
        email:
          type: string
          format: email
        platformDescription:
          type: string
        minAuthorizedExecutionTimeout:
          type: integer
          format: int64
        maxAuthorizedExecutionTimeout:
          type: integer
          format: int64
          description: 0 or absent means no max timeout. max has to be greater or equal to the min.
        defaultExecutionTimeout:
          type: integer
          format: int64
        unsupportedMethods: 
        # not present in 0.2, keep it as optional
          type: array
          items:
            type: string
          description: List of optional methods that are not supported by the platform. Must be consistent with the "isKillExecutionSupported" property.
        studiesSupport:
          type: boolean
          description:
            Whether the platform support the concept of studies, and can filter pipelines and executions from a specific study.
            Defaults to false.
        defaultStudy:
          type: string
          format: ascii
        supportedAPIVersion:
          type: string
          format: ascii
        supportedPipelineProperties:
          type: array
          items:
            type: string
          description: Complete list of all properties that can be used to describe the pipelines and to filter them in the "listPipelines" method

      additionalProperties: true # allow extensions   
    AuthenticationCredentials:
      type: object
      required:
        - username
        - password
      properties:
        username:
          type: string
        password:
          type: string
    Authentication:
      type: object
      required:
        - httpHeader
        - httpHeaderValue
      properties:
        httpHeader:
          type: string
        httpHeaderValue:
          type: string
    Pipeline:
      type: object
      required:
        - identifier
        - name
        - version
        - properties
        # - parameters optional in 0.2
      properties:
        identifier:
          type: string
          format: ascii
        name:
          type: string
        version:
          type: string
          format: ascii
        description:
          type: string
        canExecute:
          type: boolean
          description: true if the user who requested the pipeline can execute it
        parameters:
          type: array
          items:
            $ref: '#/components/schemas/PipelineParameter'
        properties:
          type: object
          additionalProperties:
            type: string
          description: the properties (as keys) and their values that describe the pipeline. 
            The properties used must be listed in the "supportedPipelineProperties" of the "getPlatformProperties" method.
        errorCodesAndMessages:
          type: array
          items:
            $ref: '#/components/schemas/ErrorCodeAndMessage'
    PipelineParameter:
      type: object
      required:
        - name
        - type
        - isOptional
        - isReturnedValue
      properties:
        name:
          type: string
          format: ascii
        type:
          $ref: '#/components/schemas/ParameterType'
        isOptional:
          type: boolean
        isReturnedValue:
          type: boolean
        defaultValue:
          description: Default value. It must be consistent with the parameter type.
        description:
          type: string
    ParameterType:
      type: string
      enum: [File,String,Boolean,Int64,Double,List]
    Execution:
      type: object
      required:
        - name
        - pipelineIdentifier
        - inputValues
      properties:
        identifier:
          type: string
          format: ascii
          readOnly: true
          description: execution id. Must always be present in responses.
        name:
          type: string
          description: execution name
        pipelineIdentifier:
          type: string
          format: ascii
          description: which pipeline that started this execution
        timeout:
          type: integer
          format: int64
          description: The timeout in seconds until which the execution is killed and deleted with all its files. 0 or absence means no timeout
        status:
          type: string
          enum: [Initializing,Ready,Running,Finished,InitializationFailed,ExecutionFailed,Unknown,Killed]
          readOnly: true
          description: The status of the execution. Must always be present in responses.
        inputValues:
          type: object
          additionalProperties: true
          description:
            Represents the input as a key/value object. The types should respect the parameters of the pipeline used for the execution.
        returnedFiles:
          type: object
          additionalProperties:
            type: array
            items: 
              type: string
              format: url
          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.
        studyIdentifier:
          type: string
          format: ascii
        errorCode:
          type: integer
          format: int64
          readOnly: true
        startDate:
          type: integer
          format: int64
          description: Time in seconds since Unix epoch
          readOnly: true
        endDate:
          type: integer
          format: int64
          description: Time in seconds since Unix epoch
          readOnly: true
    GetPathResponse :
      oneOf:
      - $ref: '#/components/schemas/BooleanResponse'
      - $ref: '#/components/schemas/Path'
      - $ref: '#/components/schemas/DirectoryList'
      - $ref: '#/components/schemas/PathMD5'
    BooleanResponse:
      description: A boolean response for "exists" action "getPath" operation
      type: object
      properties:
        exists:
          type: boolean
      required:
      - exists
    DirectoryList:
      type: array
      items:
        $ref: '#/components/schemas/Path'
      required:
      - directories
    PathMD5:
      type: object
      properties:
        md5:
          type: string
      required:
      - md5
    Path:
      type: object
      required:
      - platformPath
      - lastModificationDate
      - isDirectory
      properties:
        platformPath:
          type: string
          description: A valid path, slash-separated. It must be consistent with the path of files and directories uploaded and downloaded by clients. For instance, if a user uploads a directory structure "dir/{file1.txt,file2.txt}", it is expected that the path of the first file will be "[prefix]/dir/file1.txt" and that the path of the second file will be "[prefix]/dir/file2.txt" where [prefix] depends on the upload parameters, in particular destination directory.
        lastModificationDate:
          type: integer
          format: int64
          description: Date of last modification, in seconds since the Epoch (UNIX timestamp).
        isDirectory:
          type: boolean
          description: True if the path represents a directory.
        size:
          type: integer
          format: int64
          description: For a file, size in bytes. For a directory, sum of all the sizes of the files contained in the directory (recursively).
        executionId:
          type: string
          format: ascii
          description: Id of the Execution that produced the Path.
        mimeType:
          type: string
          format: ascii
          description: mime type based on RFC 6838.
    UploadData:
      type: object
      required:
      - base64Content
      - type
      properties:
        base64Content:
          type: string
          format: base64
          description:
            If the type is "File", the base64 string will be decoded to a single raw file.
            If the type is "Archive", the base64 string must corresponds to an encoded zip file that will be decoded to create directory and its content.
        type:
          type: string
          enum:
          - File
          - Archive
        md5:
          type: string