openEO File Storage API

openapi: 3.2.0
info:
  title: Openeo File Storage API
  version: 1.3.0
  contact:
    name: openEO Project Steering Committee
    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
  description: 'Operations tagged File Storage across 2 of this provider''s published API definitions: openeo-api-openapi.yaml, openeo-openapi.yml. Each path carries the servers of the definition it was published in.'
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 version

        numbers SHOULD be used for API versioning in the URL. To make clear

        that it is a version number, it is RECOMMENDED to add the prefix `v`.


        Example: API version `1.2.3` is recommended to use `v1`.


        The reason to only consider the major part is that backward-incompatible

        changes are introduced by major changes only. All changes from minor

        and patch releases can usually be integrated without breakages and thus

        a change in the URL is not really needed.


        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 in the

        property `api_version` from `GET /` instead.'
tags:
- name: File Storage
  description: Management of user-uploaded assets and processed data.
paths:
  /files:
    get:
      summary: List all files in the workspace
      operationId: list-files
      description: Lists all user-uploaded files that are stored at the back-end.
      tags:
      - File Storage
      security:
      - Bearer: []
      parameters:
      - $ref: '#/components/parameters/pagination_limit'
      responses:
        '200':
          description: Flattened file tree with path relative to the user's root directory and some basic properties such as the file size and the timestamp of the last modification. All properties except the name are optional. Folders MUST NOT be listed separately so each element in the list MUST be a downloadable file.
          content:
            application/json:
              schema:
                title: Workspace Files
                type: object
                required:
                - files
                - links
                properties:
                  files:
                    type: array
                    items:
                      $ref: '#/components/schemas/file'
                  links:
                    $ref: '#/components/schemas/links_pagination'
              example:
                files:
                - path: test.txt
                  size: 182
                  modified: '2015-10-20T17:22:10Z'
                - path: test.tif
                  size: 183142
                  modified: '2017-01-01T09:36:18Z'
                - path: Sentinel2/S2A_MSIL1C_20170819T082011_N0205_R121_T34KGD_20170819T084427.zip
                  size: 4183353142
                  modified: '2018-01-03T10:55:29Z'
                links: []
        4XX:
          $ref: '#/components/responses/client_error_auth'
        5XX:
          $ref: '#/components/responses/server_error'
    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 version

            numbers SHOULD be used for API versioning in the URL. To make clear

            that it is a version number, it is RECOMMENDED to add the prefix `v`.


            Example: API version `1.2.3` is recommended to use `v1`.


            The reason to only consider the major part is that backward-incompatible

            changes are introduced by major changes only. All changes from minor

            and patch releases can usually be integrated without breakages and thus

            a change in the URL is not really needed.


            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 in the

            property `api_version` from `GET /` instead.'
  /files/{path}:
    parameters:
    - name: path
      in: path
      description: 'Path of the file, relative to the user''s root directory. MAY include folders, but MUST not include relative references such as `.` and `..`.


        Folder and file names in the path MUST be url-encoded. The path separator `/` and the file extension separator `.` MUST NOT be url-encoded.


        The URL-encoding may be shown incorrectly in rendered versions due to [OpenAPI 3 not supporting path parameters which contain slashes](https://github.com/OAI/OpenAPI-Specification/issues/892). This may also lead to OpenAPI validators not validating paths containing folders correctly.'
      required: true
      schema:
        type: string
      examples:
        normal:
          description: A path without special chars. It describes a file `europe.geojson` in a folder called `borders`.
          value: borders/europe.geojson
        specialchars:
          description: A path with special chars. It describes a file `münster.shp` in folders called `europe` and `österreich`.
          value: europe/%C3%B6sterreich/m%C3%BCnster.shp
    get:
      summary: Download a file from the workspace
      operationId: download-file
      description: 'Offers a file from the user workspace for download. The file is identified by its path relative to the user''s root directory.

        If a folder is specified as path a `FileOperationUnsupported` error MUST be sent as response.'
      tags:
      - File Storage
      security:
      - Bearer: []
      responses:
        '200':
          description: A file from the workspace.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        4XX:
          $ref: '#/components/responses/client_error_auth'
        5XX:
          $ref: '#/components/responses/server_error'
    put:
      summary: Upload a file to the workspace
      operationId: upload-file
      description: 'Uploads a new file to the given path or updates an existing file if a file at the path exists.


        Folders are created once required by a file upload. Empty folders can not be created.'
      tags:
      - File Storage
      security:
      - Bearer: []
      responses:
        '200':
          description: The file has been uploaded successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/file'
        4XX:
          $ref: '#/components/responses/client_error_auth'
        5XX:
          $ref: '#/components/responses/server_error'
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
    delete:
      summary: Delete a file from the workspace
      operationId: delete-file
      description: 'Deletes an existing user-uploaded file specified by its path. Resulting empty folders MUST be deleted automatically.


        Back-ends MAY support deleting folders including its files and sub-folders. If not supported by the back-end a `FileOperationUnsupported` error MUST be sent as response.'
      tags:
      - File Storage
      security:
      - Bearer: []
      responses:
        '204':
          description: The file has been successfully deleted at the back-end.
        4XX:
          $ref: '#/components/responses/client_error_auth'
        5XX:
          $ref: '#/components/responses/server_error'
    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 version

            numbers SHOULD be used for API versioning in the URL. To make clear

            that it is a version number, it is RECOMMENDED to add the prefix `v`.


            Example: API version `1.2.3` is recommended to use `v1`.


            The reason to only consider the major part is that backward-incompatible

            changes are introduced by major changes only. All changes from minor

            and patch releases can usually be integrated without breakages and thus

            a change in the URL is not really needed.


            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 in the

            property `api_version` from `GET /` instead.'
components:
  responses:
    server_error:
      description: 'The request can not be fulfilled due to an error at the back-end. The

        error is never the client’s fault and therefore it is reasonable for the

        client to retry the exact same request that triggered this response.


        The response body SHOULD contain a JSON error object. MUST be any HTTP

        status code specified in [RFC 7231](https://www.rfc-editor.org/rfc/rfc7231.html#section-6.6).


        See also:

        * [Error Handling](#section/API-Principles/Error-Handling) in the API in general.

        * [Common Error Codes](errors.json)'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
    client_error_auth:
      description: 'The request can not be fulfilled due to an error on client-side, i.e. the

        request is invalid. The client SHOULD NOT repeat the request without

        modifications.


        The response body SHOULD contain a JSON error object.

        MUST be any HTTP status code specified in [RFC 7231](https://www.rfc-editor.org/rfc/rfc7231.html#section-6.6).

        This request MUST respond with HTTP status codes 401 if authorization is required or

        403 if the authorization failed or access is forbidden in general to the

        authenticated user. HTTP status code 404 SHOULD be used if the value of

        a path parameter is invalid.


        See also:

        * [Error Handling](#section/API-Principles/Error-Handling) in the API in general.

        * [Common Error Codes](errors.json)'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
  schemas:
    log_links:
      description: 'Links related to this log entry / error, e.g. to a resource that

        provides further explanations.


        For relation types see the lists of

        [common relation types in openEO](#section/API-Principles/Web-Linking).'
      type: array
      items:
        $ref: '#/components/schemas/link'
      example:
      - href: https://openeo.example/docs/errors/SampleError
        rel: about
    log_code:
      type: string
      description: The code is either one of the standardized error codes or a custom code, for example specified by a user in the `inspect` process.
      example: SampleError
    link:
      title: Link
      description: A link to another resource on the web. Bases on [RFC 5899](https://www.rfc-editor.org/rfc/rfc5988.html).
      type: object
      required:
      - href
      - rel
      properties:
        rel:
          type: string
          description: Relationship between the current document and the linked document. SHOULD be a [registered link relation type](https://www.iana.org/assignments/link-relations/link-relations.xml) whenever feasible.
          example: related
        href:
          type: string
          description: The value MUST be a valid URL.
          format: uri
          example: https://openeo.example
        type:
          type: string
          description: The value MUST be a string that hints at the format used to represent data at the provided URI, preferably a media (MIME) type.
          example: text/html
        title:
          type: string
          description: Used as a human-readable label for a link.
          example: openEO
    file:
      title: Workspace File
      type: object
      required:
      - path
      properties:
        path:
          type: string
          description: 'Path of the file, relative to the root directory of the user''s server-side workspace.

            MUST NOT start with a slash `/` and MUST NOT be url-encoded.


            The Windows-style path name component separator `\` is not supported,

            always use `/` instead.


            Note: The pattern only specifies a minimal subset of invalid characters.

            The back-ends MAY enforce additional restrictions depending on their OS/environment.'
          example: folder/file.txt
          pattern: ^[^/\r\n\t\\:'"][^\r\n\t\\:'"]*$
        size:
          type: integer
          description: File size in bytes.
          example: 1024
        modified:
          type: string
          format: date-time
          description: Date and time the file has lastly been modified, formatted as a [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) date-time.
          example: '2018-01-03T10:55:29Z'
    error:
      title: General Error
      description: 'An error object declares additional information about a client-side or server-side error.

        See also: * [Error Handling](#section/API-Principles/Error-Handling) in the API in general. * [Common Error Codes](errors.json)'
      type: object
      required:
      - code
      - message
      properties:
        id:
          type: string
          description: A back-end MAY add a unique identifier to the error response to be able to log and track errors with further non-disclosable details. A client could communicate this id to a back-end provider to get further information.
          example: 550e8400-e29b-11d4-a716-446655440000
        code:
          $ref: '#/components/schemas/log_code'
        message:
          type: string
          description: A message explaining what the client may need to change or what difficulties the server is facing.
          example: Parameter 'sample' is missing.
        links:
          $ref: '#/components/schemas/log_links'
    links_pagination:
      description: 'Links related to this list of resources, for example links for pagination

        or alternative formats such as a human-readable HTML version.

        The links array MUST NOT be paginated.


        If pagination is implemented, the following `rel` (relation) types apply:


        1. `next` (REQUIRED): A link to the next page, except on the last page.


        2. `prev` (OPTIONAL): A link to the previous page, except on the first page.


        3. `first` (OPTIONAL): A link to the first page, except on the first page.


        4. `last` (OPTIONAL): A link to the last page, except on the last page.


        For additional relation types see also the lists of

        [common relation types in openEO](#section/API-Principles/Web-Linking).'
      type: array
      items:
        $ref: '#/components/schemas/link'
  parameters:
    pagination_limit:
      name: limit
      description: 'This parameter enables pagination for the endpoint and specifies the maximum number of

        elements that arrays in the top-level object (e.g. collections, processes, batch jobs,

        secondary services, log entries, etc.) are allowed to contain.

        The `links` array MUST NOT be paginated like the resources,

        but instead contain links related to the paginated resources

        or the pagination itself (e.g. a link to the next page).

        If the parameter is not provided or empty, all elements are returned.


        Pagination is OPTIONAL: back-ends or clients may not support it.

        Therefore, it MUST be implemented in a way that clients not supporting

        pagination get all resources regardless. Back-ends not supporting

        pagination MUST return all resources.


        If the response is paginated, the `links` array MUST be used to communicate the

        links for browsing the pagination with predefined `rel` types. See the `links` array schema

        for supported `rel` types.

        Back-end implementations can, unless specified otherwise, use any kind of pagination technique,

        depending on what is supported best by their infrastructure: page-based, offset-based, token-based

        or something else. The clients SHOULD use whatever is specified

        in the links with the corresponding `rel` types.'
      in: query
      allowEmptyValue: true
      example: 10
      schema:
        type: integer
        minimum: 1
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT or openEO
      description: "A Bearer token can be provided in two different formats:\n1. **JSON Web Token (JWT) - RECOMMENDED**\n\n   - Conformance class: `https://api.openeo.org/1.3.0/authentication/jwt`\n   \n   The Bearer token is an access token in [JWT](https://datatracker.ietf.org/doc/html/rfc7519) format\n   as defined in RFC 7519. For openEO, it MUST include the issuer in the\n   `iss` claim although being optional in RFC 7519.\n   If the concept of an issuer does not exist in an authentication method (e.g. in HTTP Basic),\n   implementations could use the endpoint for Basic Authentication as the issuer, for example.\n\n   openEO backend implementations MUST signal their support for JWT by listing the given\n   conformance class. Likewise, openEO clients SHOULD only use JWT when the openEO backend\n   lists the conformance class.\n\n2. **openEO Tokens - DEPRECATED**\n\n   - Conformance class: *None*\n\n   The Bearer Token is constructed from the authentication method, a\n   provider ID (if available) and the access token. All separated by a\n   forward slash `/`.\n\n   Examples (replace `TOKEN` with the actual access token):\n\n   - Basic authentication (no provider ID available): `basic//TOKEN`\n   - OpenID Connect (provider ID is `ms`): `oidc/ms/TOKEN`.\n     For OpenID Connect, the provider ID corresponds to the value\n     specified for `id` for each provider in `GET /credentials/oidc`.\n\n   All openEO backends MUST accept this method for backward compatibility\n   until version 2.0 of the specification.\n\n   The access tokens provided by the identity provider do not include\n   the prefix that includes the authentication method and provider ID.\n   The Bearer Token sent to the openEO backend MUST have the prefix, e.g. `basic//` for Basic authentication.\n   This means that the clients have to prepend the prefix.\n\nJWT and openEO tokens can be distinguished by the presence of a slash `/` in the token, which JWT can never contain due to the Base64 encoding."
    Basic:
      type: http
      scheme: basic
externalDocs:
  description: openEO Documentation
  url: https://openeo.org/documentation/1.0/
x-refined-from:
- openeo-api-openapi.yaml
- openeo-openapi.yml