openapi.yml

openapi: '3.0.1'
info:
  title: Anonymization/Synthetization Service
  version: '1.0'
servers:
  - url: https://api.server.test/v1
security:
  - ApiKeyAuth: []


paths:
  /job:
    post:
      tags:
        - jobs
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Job'


      responses:
        '201':
          description: Create new job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
    get:
      tags:
        - jobs
      parameters:
        - in: query
          name: page
          schema:
            type: integer
            minimum: 1
          description: "Page index to display (starting at 1)"
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 100
          description: "Jobs to display per page"
      responses:
        '200':
          description: List existing Jobs
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Job'
        
  /job/{jobId}:
    get:
      tags:
        - jobs
      parameters:
        - name: jobId
          in: path
          description: "The id of the job to fetch"
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Get job status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
  /job/{jobId}/task/{taskId}/assets/{assetId}:
      get:
        tags:
          - jobs
        parameters:
          - name: jobId
            in: path
            description: "The id of the job"
            required: true
            schema:
              type: string
          - name: taskId
            in: path
            description: "The id of the task"
            required: true
            schema:
              type: string
          - name: assetId
            in: path
            description: "The id of the asset to fetch"
            required: true
            schema:
              type: string
        responses:
          '200':
            description: Download task asset
            content:
              application/octet-stream:
                schema:
                  $ref: '#/components/schemas/TaskAsset'
          '404':
            description: Task asset not found
            content:
              application/json:
                schema:
                  type: string
          '403':
            description: Task asset access forbidden
            content:
              application/json:
                schema:
                  type: string
          '401':
            description: Not Authenticated
            content:
              application/json:
                schema:
                  type: string

components:
  securitySchemes:
      ApiKeyAuth:        # arbitrary name for the security scheme
        type: apiKey
        in: header       # can be "header", "query" or "cookie"
        name: X-DEID-API-KEY
  schemas:
    Job:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        userId:
          type: string
          format: uuid
          readOnly: true
        name:
          type: string
        deidentificationMethod:
          type: object
          oneOf:
            - $ref: '#/components/schemas/ArxAnonymizationSingleTable'
            - $ref: '#/components/schemas/MostlyAiSynthetisationSingleTable'
          discriminator:
            propertyName: type
            mapping:
              ARX_SINGLE_TABLE: '#/components/schemas/ArxAnonymization'
              MOSTLY_AI_SINGLE_TABLE: '#/components/schemas/MostlyAiSynthetisation'
        status:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/JobState'
        tasks:
          type: array
          readOnly: true
          items:
            oneOf:
              - $ref: '#/components/schemas/ArxAnonymisationTask'
              - $ref: '#/components/schemas/ReviewTask'

    JobState:
      type: string
      enum:
        - NEW
        - QUEUED
        - RUNNING
        - FINISHED
        - FAILED
    Task: # abstract
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/JobState'
        name:
          type: string
        progress:
          type: number
          format: float
          minimum: 0
          maximum: 1
        assets:
          type: object
          properties:
            id:
              type: string
              format: uuid
            name: 
              type: string
    ArxAnonymisationTask:
      type: object
      allOf:
        - $ref: '#/components/schemas/Task'
        - type: object
          properties:
            configuration:
              readOnly: true
              allOf:
                - $ref: '#/components/schemas/ArxAnonymizationSingleTable'
              
    ReviewTask:
      type: object
      allOf:
        - $ref: '#/components/schemas/Task'
        - type: object
          properties:
            approvalState:
              type: string
              enum:
                - OPEN
                - APPROVED
                - DECLINED
            decisionMessage:
              type: string
    TypeId:
      type: object
      properties:
        type:
          type: string
      required:
        - type
    ArxAnonymizationSingleTable:
      type: object
      allOf:
        - $ref: '#/components/schemas/TypeId'
        - type: object
          properties:
            queryId:
              type: string
              format: uuid
            suppressionLimit:
              type: number
              format: float
              minimum: 0
              maximum: 1
            privacyModel:
              type: string
              enum:
                - K_ANONYMITY_5
                - K_ANONYMITY_11
                - PITMAN_1
      required:
        - queryId
        - suppressionLimit
        - privacyModel
    MostlyAiSynthetisationSingleTable:
      type: object
      allOf:
        - $ref: '#/components/schemas/TypeId'
        - type: object
          properties:
            queryId:
              type: string
              format: uuid
      required:
        - queryId
    TaskAsset:
      type: string
      format: binary
      readOnly: true