openapi: 3.0.2
info:
  title: openEO API - Workspaces Extension
  version: 0.1.0
  description: |-
    The Workspace Extension to the openEO API provides an interface for connecting external file storage such as cloud buckets to openEO back-end implementations. This allows for example to store batch job results on such file storage systems.

    The Workspace API is inspired by the [EOEPCA Workspace API](https://github.com/EOEPCA/rm-workspace-api) with regards to workspace management.
  contact:
    name: openEO Consortium
    url: 'https://openeo.org'
    email: openeo.psc@uni-muenster.de
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
externalDocs:
  url: https://github.com/Open-EO/openeo-api/blob/draft/extensions/workspaces/README.md
tags:
  - name: Workspaces
    description: Management of User Workspaces
servers:
  - url: 'https://openeo.example/api/{version}'
    description: >-
      The URL of the API MAY freely be chosen by the back-end providers. The
      path, including API versioning, is a *recommendation* only. Nevertheless,
      all servers MUST support HTTPS as the authentication methods are not
      secure with HTTP only!
    variables:
      version:
        default: v1
        description: >-
          API versioning is RECOMMENDED. As the openEO API is following
          [SemVer](https://semver.org/) only the MAJOR part of the stable
          version numbers (i.e. versions >= 1.0.0) SHOULD be used for API
          versioning in the URL. The reason is that backward-incompatible
          changes are usually introduced by major changes. Therefore, the
          version number in the URL MUST not be used by the clients to detect
          the version number of the API. Use the version number returned from
          `GET /` instead.
paths:
  /workspaces:
    get:
      summary: List all workspaces
      operationId: list-workspaces
      description: |-
        Lists all workspaces that have been added by a user.
        
        It is **strongly RECOMMENDED** to keep the response size small by
        omitting all optional non-scalar values (i.e. arrays and objects) from objects in `workspaces`.
        To get the full metadata for a workspace clients MUST request `GET /workspaces/{workspace_id}`.
      tags:
        - Workspaces
      security:
        - Bearer: []
      parameters:
        - $ref: '../../openapi.yaml#/components/parameters/pagination_limit'
      responses:
        '200':
          description: Array of workspace descriptions
          content:
            application/json:
              schema:
                title: Workspaces
                type: object
                required:
                  - workspaces
                  - links
                properties:
                  workspaces:
                    type: array
                    items:
                      $ref: '#/components/schemas/workspace'
                  links:
                    $ref: '../../openapi.yaml#/components/schemas/links_pagination'
        4XX:
          $ref: '../../openapi.yaml#/components/responses/client_error_auth'
        5XX:
          $ref: '../../openapi.yaml#/components/responses/server_error'
    post:
      summary: Create Workspace
      operationId: create-workspace
      description: |-
        Creates a new workspace.

        This request queues the creation of a workspace. It directly registers an id at the back-end, but the workspace itself may have a status of `provisioning` until the workspace is ready to use.
      tags:
        - Workspaces
      security:
        - Bearer: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - intent
              properties:
                title:
                  $ref: '#/components/schemas/workspace_title'
                description:
                  $ref: '#/components/schemas/workspace_description'
                intent:
                  type: string
                quota:
                  $ref: '../../openapi.yaml#/components/schemas/max_storage_quota'
              oneOf:
                - title: Create workspace
                  properties:
                    intent:
                      enum:
                        - create
                      example: create
                - title: Register existing workspace
                  required:
                    - url
                    - credentials
                  properties:
                    intent:
                      enum:
                        - register
                      example: register
                    url:
                      $ref: '#/components/schemas/workspace_url'
                    credentials:
                      $ref: '#/components/schemas/workspace_credentials'
        required: true
      responses:
        '201':
          description: The workspace creation has been queued successfully.
          headers:
            Location:
              required: true
              schema:
                description: |-
                  Absolute URL to the workspace metadata.
                  
                  The URL points to the endpoint
                  `GET /workspaces/{workspace_id}` with the `{workspace_id}` being the
                  id of the created workspace.
                format: uri
                type: string
                example: 'https://openeo.example/api/v1/workspaces/my-workspace'
            OpenEO-Identifier:
              required: true
              schema:
                $ref: '#/components/schemas/workspace_id'
        4XX:
          $ref: '../../openapi.yaml#/components/responses/client_error_auth'
        5XX:
          $ref: '../../openapi.yaml#/components/responses/server_error'
  /workspaces/{workspace_id}:
    parameters:
      - $ref: '#/components/parameters/workspace_id'
    get:
      summary: Full metadata for a workspace
      operationId: describe-workspace
      description: >-
        Returns the full metadata for a workspace.
      tags:
        - Workspaces
      security:
        - Bearer: []
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/workspace'
        4XX:
          $ref: '../../openapi.yaml#/components/responses/client_error_auth'
        5XX:
          $ref: '../../openapi.yaml#/components/responses/server_error'
    delete:
      summary: Delete Workspace
      operationId: delete-workspace
      description: |-
        Removes the workspace from the backend.
      tags:
        - Workspaces
      security:
        - Bearer: []
      responses:
        '204':
          description: The workspace has been successfully deleted.
        4XX:
          $ref: '../../openapi.yaml#/components/responses/client_error_auth'
        5XX:
          $ref: '../../openapi.yaml#/components/responses/server_error'
    patch:
      summary: Update workspace details
      operationId: update-workspace
      description: >-
        Updates the workspace details.
      tags:
        - Workspaces
      security:
        - Bearer: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  $ref: '#/components/schemas/workspace_title'
                description:
                  $ref: '#/components/schemas/workspace_description'
        required: true
      responses:
        '204':
          description: Changes to the workspace were applied successfully.
        4XX:
          $ref: '../../openapi.yaml#/components/responses/client_error_auth'
        5XX:
          $ref: '../../openapi.yaml#/components/responses/server_error'
components:
  parameters:
    workspace_id:
      name: workspace_id
      in: path
      required: true
      description: The ID of the workspace.
      schema:
        $ref: '#/components/schemas/workspace_id'
  schemas:
    workspace_id:
      type: string
      pattern: '^[\w\-\.~]+$'
      example: my-workspace
    workspace_title:
      type: string
      description: A short title for the workspace.
    workspace_description:
      type: string
      format: commonmark
      description: |-
        A description that describes the workspace.

        [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich
        text representation.
    workspace:
      title: Workspace
      required:
        - id
        - status
      type: object
      properties:
        id:
          $ref: '#/components/schemas/workspace_id'
        title:
          $ref: '#/components/schemas/workspace_title'
        description:
          $ref: '#/components/schemas/workspace_description'
        status:
          type: string
          description: The status of the workspace.
        details:
          type: string
          description: >-
            A status message (e.g. error message) or any other free-text information about the workspace.
        quota:
          $ref: '../../openapi.yaml#/components/schemas/max_storage_quota'
      oneOf:
        - title: Unavailable
          description:
            The workspace is not available, e.g. because it's still provisioning it
            or the back-end can't connect to it / lost the connection / has been deleted externally, ...
          properties:
            status:
              enum:
                - provisioning
                - unavailable
              example: provisioning
        - title: Ready
          properties:
            status:
              enum:
                - ready
              example: ready
            url:
              $ref: '#/components/schemas/workspace_url'
            credentials:
              $ref: '#/components/schemas/workspace_credentials'
            properties:
              $ref: '#/components/schemas/workspace_properties'
            free:
              $ref: '../../openapi.yaml#/components/schemas/storage_quota_free'
    workspace_url:
      type: string
      format: uri
      description: The URL of the actual workspace, e.g. a bucket URL.
      example: 'https://my-bucket.s3.eu-west-3.amazonaws.com'
    workspace_credentials:
      type: object
      description: >-
        Credentials to access the workspace as required by the workspace provider.
        The structure is not specified by the API.
      additionalProperties:
        type: string
      example:
        username: john_doe
        password: secret123
    workspace_properties:
      type: object
      description: >-
        Any additional metadata of the workspace provided by the workspace provider.
        The structure is not specified by the API.
      additionalProperties:
        description: Any type
      example:
        region: eu-west-3
        storage_class: standard
  securitySchemes:
    Bearer:
      $ref: '../../openapi.yaml#/components/securitySchemes/Bearer'