openapi: 3.1.0
info:
  title: ETHZ Archiver Service
  description: REST API endpoint provider for presigned S3 upload and archiving workflow scheduling
  version: 0.1.0
servers:
  - url: /
security:
  - BearerAuth: []
paths:
  /health/livez:
    get:
      security: []
      summary: Health Check
      description: Returns the health status of the service
      tags:
        - health
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "healthy"
                  timestamp:
                    type: string
                    format: date-time
                    example: "2023-10-01T12:00:00Z"
        '503':
          description: Service is unavailable
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "unhealthy"
                  error:
                    type: string
                    example: "Service is down"
  /health/readyz:
    get:
      security: []
      summary: Readiness Check
      description: Returns the Readiness status of the service
      tags:
        - health
      responses:
        '200':
          description: Service is ready
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "Ready"
                  timestamp:
                    type: string
                    format: date-time
                    example: "2023-10-01T12:00:00Z"
        '503':
          description: Service is not ready 
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "not ready"
                  error:
                    type: string
                    example: "Service is not ready"
  /token:
    post:
      security:
        - SciCatAuth: []
      operationId: create_new_service_token
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateServiceTokenResp"
          description: Service Token created
        "422":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
          description: Validation Error
        "500":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InternalError"
          description: Internal Server Error
      summary: Create New Service Token
      tags:
        - service_token
  /archiver/jobs:
    post:
      security: 
        - BasicAuth: []
      operationId: create_job
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateJobBody"
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateJobResp"
          description: Job Created
        "422":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
          description: Data Validation Error
        "500":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InternalError"
          description: Internal Server Error
      summary: Create Archiver Job
      tags:
        - archiving
  /s3/requestDatasetUpload:
    post:
      operationId: request_dataset_upload
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UploadRequestBody"
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UploadRequestSuccessfulResp"
          description: Upload request successful
        "507":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UploadRequestUnsuccessfulResp"
          description: Upload request unsuccessful
        "422":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
          description: Validation Error
        "500":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InternalError"
          description: Internal Server Error
      summary: Request a new upload
      tags:
        - s3upload

  /s3/presignedUrls:
    post:
      operationId: get_presigned_urls
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PresignedUrlBody"
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PresignedUrlResp"
          description: Presigned URLs created
        "422":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
          description: Validation Error
        "500":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InternalError"
          description: Internal Server Error
      summary: Get Presigned urls
      tags:
        - s3upload
  /s3/completeUpload:
    post:
      operationId: complete_upload
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CompleteUploadBody"
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CompleteUploadResp"
          description: Upload completed
        "422":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
          description: Validation Error
        "500":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InternalError"
          description: Internal Server Error
      summary: Complete Upload
      tags:
        - s3upload
  /s3/abortMultipartUpload:
    post:
      operationId: abort_multipart_upload
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AbortUploadBody"
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AbortUploadResp"
          description: Abort multipart upload requested
        "422":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
          description: Validation Error
        "500":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InternalError"
          description: Internal Server Error
      summary: Abort Multipart Upload
      tags:
        - s3upload
  /s3/finalizeDatasetUpload:
    post:
      operationId: FinalizeDatasetUpload
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FinalizeDatasetUploadBody"
        required: true
      responses:
        "201":
          description: Finalize dataset upload requested
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FinalizeDatasetUploadResp"
        "422":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
          description: Validation Error
        "500":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InternalError"
          description: Internal Server Error
      summary: Finalize Dataset Upload
      tags:
        - s3upload
  /s3/abortDatasetUpload:
    post:
      operationId: AbortDatasetUpload
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AbortDatasetUploadBody"
        required: true
      responses:
        "201":
          description: Finalize dataset upload requested
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AbortDatasetUploadResp"
        "422":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
          description: Validation Error
        "500":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InternalError"
          description: Internal Server Error
      summary: Abort Dataset Upload
      tags:
        - s3upload
components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    BearerAuth: # RS256 tokens signed by Keycloak
      type: http
      scheme: bearer
      bearerFormat: JWT # optional, but indicates the format of the token
    SciCatAuth: # HS256 tokens signed by SciCat
      type: http
      scheme: bearer
      bearerFormat: JWT # optional, but indicates the format of the token
  schemas:
    CreateServiceTokenResp:
      properties:
        access_token:
          type: string
          description: The JWT access token
        expires_in:
          type: integer
          description: The duration in seconds the access token is valid for
          example: 300
        refresh_token:
          type: string
          description: The JWT refresh token
        refresh_expires_in:
          type: integer
          description: The duration in seconds the refresh token is valid for
          example: 1800
        token_type:
          type: string
          description: Bearer
          example: Bearer
        not-before-policy:
          type: integer
          description: Timestamp that indicates the time before which the JWT must not be accepted for processing
          example: 0
        session_state:
          type: string
          description: Session id, identifier that uniquely ties the session to the authenticated user
          example: ec313d7a-df9d-4390-865e-c6d606156fdc
        scope:
          type: string
          description: Claim in a JWT defines the set of permissions or access rights granted
          example: email profile
      required:
        - access_token
        - refresh_token
      title: CreateServiceTokenResp
    AbortUploadBody:
      example:
        upload_id: upload_id
        object_name: object_name
      properties:
        dataset_id:
          title: dataset_id
          type: string
        upload_id:
          title: upload_id
          type: string
        object_name:
          title: object_name
          type: string
      required:
        - object_name
        - upload_id
        - dataset_id
      title: AbortUploadBody
    AbortUploadResp:
      example:
        upload_id: upload_id
        object_name: object_name
        message: Succeeded
      properties:
        message:
          title: message
          type: string
        upload_id:
          title: upload_id
          type: string
        object_name:
          title: object_name
          type: string
      required:
        - object_name
        - upload_id
        - message
      title: AbortUploadResp
    CompletePart:
      example:
        part_number: 0
        etag: etag
        checksum_sha256: checksum_sha256
      properties:
        part_number:
          title: part_number
          type: integer
        etag:
          title: etag
          type: string
        checksum_sha256:
          title: checksum_sha256
          type: string
      required:
        - checksum_sha256
        - etag
        - part_number
      title: CompletePart
    CompleteUploadBody:
      example:
        parts:
          - part_number: 0
            etag: etag
            checksum_sha256: checksum_sha256
          - part_number: 0
            etag: etag
            checksum_sha256: checksum_sha256
        upload_id: upload_id
        object_name: object_name
        checksum_sha256: checksum_sha256
      properties:
        dataset_id:
          title: dataset_id
          type: string
        object_name:
          title: object_name
          type: string
        upload_id:
          title: upload_id
          type: string
        parts:
          items:
            $ref: "#/components/schemas/CompletePart"
          title: parts
          type: array
        checksum_sha256:
          title: checksum_sha256
          type: string
      required:
        - dataset_id
        - checksum_sha256
        - object_name
        - parts
        - upload_id
      title: CompleteUploadBody
    CompleteUploadResp:
      example:
        location: http://minio/object
        key: object_name
      properties:
        location:
          title: location
          type: string
        key:
          title: key
          type: string
      required:
        - location
        - key
      title: CompleteUploadResp
    CreateJobBody:
      properties:
        id:
          title: id
          type: string
          format: uuid
        type:
          title: type
          type: string
          enum: [archive, retrieve]
      required:
        - id
        - type
      title: CreateJobBody
    CreateJobResp:
      properties:
        uuid:
          title: JobID
          type: string
          format: uuid
        name:
          title: JobName
          type: string
      required:
        - uuid
        - name
      title: CreateJobResp
    AbortDatasetUploadBody:
      example:
        dataset_id: c2c6bc13-2c14-43d7-91a9-46cd556b258d
      properties:
        dataset_id:
          title: dataset_id
          type: string
      required:
        - dataset_id
      title: AbortDatasetUploadBody
    AbortDatasetUploadResp:
      example:
        dataset_id: dataset_id
        message: "Upload finalized"
      properties:
        dataset_id:
          title: dataset_id
          type: string
        message:
          title: message
          type: string
      required:
        - dataset_id
        - message
      title: AbortDatasetUploadResp
    FinalizeDatasetUploadBody:
      example:
        dataset_id: c2c6bc13-2c14-43d7-91a9-46cd556b258d
        create_archiving_job: true
        owner_group: Group
        owner_user: User
        contact_email: user@mail.com
      properties:
        dataset_id:
          title: dataset_id
          type: string
        create_archiving_job:
          title: create_archiving_job
          type: boolean
        owner_group:
          title: owner_group
          type: string
        owner_user:
          title: owner_user
          type: string
        contact_email:
          title: contact_email
          type: string
          format: email
      required:
        - dataset_id
        - create_archiving_job
        - owner_group
        - owner_user
        - contact_email
      title: FinalizeDatasetUploadBody
    FinalizeDatasetUploadResp:
      example:
        dataset_id: dataset_id
        message: "Upload finalized"
      properties:
        dataset_id:
          title: dataset_id
          type: string
        message:
          title: message
          type: string
      required:
        - dataset_id
        - message
      title: FinalizeDatasetUploadResp
    HTTPValidationError:
      example:
        detail:
          - msg: msg
            loc:
              - ValidationError_loc_inner
              - ValidationError_loc_inner
            type: type
          - msg: msg
            loc:
              - ValidationError_loc_inner
              - ValidationError_loc_inner
            type: type
      properties:
        detail:
          items:
            $ref: "#/components/schemas/ValidationError"
          title: detail
          type: array
      title: HTTPValidationError
    InternalError:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: A specific error code indicating the error type
        message:
          type: string
          description: A human-readable message providing more details about the error
        details:
          type: string
          description: Additional context or information about the error
        timestamp:
          type: string
          format: date-time
          description: The time when the error occurred
    PresignedUrlBody:
      example:
        parts: 0
        object_name: object_name
      properties:
        dataset_id:
          title: DatasetPID
          type: string
        object_name:
          title: object_name
          type: string
        parts:
          title: parts
          type: integer
          minimum: 1
      required:
        - object_name
        - parts
        - dataset_id
      title: PresignedUrlBody
    PresignedUrlResp:
      example:
        urls:
          - urls
          - urls
        upload_id: upload_id
      properties:
        upload_id:
          title: upload_id
          type: string
        urls:
          items:
            type: string
          title: urls
          type: array
      required:
        - upload_id
        - urls
      title: PresignedUrlResp
    UploadRequestBody:
      example:
        dataset_id:
          - dataset/pid
        dataset_size_gib: 1000
      properties:
        dataset_id:
          title: DatasetPID
          type: string
        dataset_size_gib:
          title: Size in GiB
          type: integer
      required:
        - dataset_id
        - dataset_size_gib
      title: UploadRequestBody
    UploadRequestSuccessfulResp:
      example:
        message: upload granted
      properties:
        message:
          title: message
          type: string
      required:
        - message
      title: UploadRequestSuccessfulResp
    UploadRequestUnsuccessfulResp:
      example:
        message: not enough storage
      properties:
        message:
          title: message
          type: string
        dataset_id:
          title: dataset_id
          type: string
        requested_size_gib:
          title: requested size in GiB
          type: integer
      required:
        - message 
        - dataset_id
        - requested_size_gib
      title: UploadRequestUnsuccessfulResp
    ValidationError:
      example:
        msg: msg
        loc:
          - ValidationError_loc_inner
          - ValidationError_loc_inner
        type: type
      properties:
        loc:
          items:
            $ref: "#/components/schemas/ValidationError_loc_inner"
          title: loc
          type: array
        msg:
          title: message
          type: string
        type:
          title: Error type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationError
    ValidationError_loc_inner:
      anyOf:
        - type: string
        - type: integer
      title: ValidationError_loc_inner