openapi: 3.0.0
info:
  description: Entrusted REST API for document sanitization
  version: "1"
  title: entrusted-webserver-api
tags:
  - name: entrusted
    description: Entrusted WebServer REST Operations
paths:
  "/api/v1/uitranslations":
    get:
      operationId: uitranslations
      summary: HTML Web UI translation messages by key
      tags:
        - entrusted
      responses:
        200:
          description: Request accepted and queued for processing
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TranslationResponse"
  "/api/v1/upload":
    post:
      operationId: upload
      summary: Upload a document to sanitize
      tags:
        - entrusted
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: The document binary data
                filename:
                  type: string
                  description: The name of the document to process
                ocrlang:
                  type: string
                  description: |
                    Optional tesseract language code for optional character recognition (OCR).
                    See https://tesseract-ocr.github.io/tessdoc/Data-Files-in-different-versions.html
                docpasswd:
                  type: string
                  description: Optional password for the encrypted Office or PDF document
                visualquality:
                  type: string
                  enum: [low, medium, high]
                  description: The desired PDF result visual quality
              required: ['file', 'filename']
      responses:
        202:
          description: Request accepted and queued for processing
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/UploadResponse"
        400:
          $ref: "#/components/schemas/ProblemDetailsResponse"
        500:
          $ref: "#/components/schemas/ProblemDetailsResponse"
  "/api/v1/events/{request_id}":
    get:
      operationId: events
      summary: Fetch processing notifications
      description: This is a stream of server-sent events
      tags:
        - entrusted
      parameters:
        - name: request_id
          in: "path"
          description: The request system identifier
          required: true
          example: "USm3fpXnKG5EUBx2ndxBDMPVciP5hGey2Jh4NDv6gmeo1LkMeiKrLJUUBk6Z"
          schema:
            type: string
      responses:
        200:
          description: |
            Request accepted and queued for processing.
            
            Please note that OpenAPI has no support for SSE events, only the data field is in JSON format.
          content:
            text/event-stream:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/EventStreamItemResponse"
              examples:
                success:
                  value:
                    - id: 1
                      event: processing_update
                      data: "{'data': 'stuff', 'type': 'processing_update', 'percent_complete': 1}"
                    - id: 2
                      event: processing_success
                      data: "{'data': 'success', 'type': 'processing_success', 'percent_complete: 100}"
                failure:
                  value: 
                    - id: 1
                      event: processing_update
                      data: "{'data': 'stuff', 'type': 'processing_update', 'percent_complete': 1}"
                    - id: 2
                      event: processing_failure
                      data: "{'data': 'failure', 'type': 'processing_failure', 'percent_complete': 100}"
                      
        404:
          $ref: "#/components/schemas/ProblemDetailsResponse"
  "/api/v1/downloads/{request_id}":
    get:
      operationId: downloads
      summary: |
        Download the resulting PDF for a given request
      description: |
        This is to be invoked after receiving a processing_success message from 'events' confirming the sanitization process completion.

        Please note that the trusted PDF result is automatically deleted upon download.
      tags:
        - entrusted
      parameters:
        - in: path
          name: request_id
          description: The request system identifier
          required: true
          example: "USm3fpXnKG5EUBx2ndxBDMPVciP5hGey2Jh4NDv6gmeo1LkMeiKrLJUUBk6Z"
          schema:
            type: string
      responses:
        200:
          description: Request accepted and queued for processing
          content:
            application/pdf:
              schema:
                type: string
                format: binary
                description: The trusted PDF binary contents
        404:
          $ref: "#/components/schemas/ProblemDetailsResponse"
        500:
          $ref: "#/components/schemas/ProblemDetailsResponse"
components:
  schemas:
    UploadResponse:
      description: Upload response
      properties:
        request_id:
          type: string
          description: |
            Request system identifier encoded in base58 format.
            
            The underlying value follows the format base64_fileuuid;base64_filename.
            
            This helps set a reasonable output file name once the file is ready for download later.
          example: USm3fpXnKG5EUBx2ndxBDMPVciP5hGey2Jh4NDv6gmeo1LkMeiKrLJUUBk6Z
        tracking_uri:
          type: string
          description: URI location for fetching processing notifications
          example: /events/USm3fpXnKG5EUBx2ndxBDMPVciP5hGey2Jh4NDv6gmeo1LkMeiKrLJUUBk6Z
    TranslationResponse:
      description: Translation response
      properties:
        locale:
          type: string
          description: The language code which is following either ISO 639-1 or RFC4647 for specialized languages
          example: en
        data:
          type: object
          additionalProperties:
            type: string
          description: Translation values by message key
          example:
           "translation_key_first": "translation_value_first"
           "translation_key_other": "translation_value_other"
    EventStreamItemResponse:
      description: |
        Server-Sent event notification.
        
        See https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events
      properties:
        id:
          type: integer
          description: The event id
          example: 123
        event:
          type: string
          description: The event type
          example: processing_update
        data:
          type: object
          description: The event data in JSON format
          format: json
          example: "{'data': 'doing stuff', 'percent_complete': 100}"
    ProblemDetailsResponse:
      description: Error response following the RFC7807 Problem Details specification at https://tools.ietf.org/html/rfc7807
      properties:
        status:
          type: integer
          format: int32
          description: The HTTP status code
          example: 500
        title:
          type: string
          description: A short, human-readable summary of the problem type
          example: Internal server error
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem
          example: An IO error occurred
        instance:
          type: string
          description: A URI reference that identifies the specific occurrence of the problem
          example: /api/v1/events/insert-request-identifier-here