openapi: 3.0.2
info:
  title: PHAIDRA datastream imageserver API
  version: '3.0'
  description: Documentation of the PHAIDRA API.
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- description: University of Vienna PHAIDRA
  url: https://services.phaidra.univie.ac.at/api/
- description: PHAIDRA Sandbox
  url: https://sandbox.phaidra.org/api/
tags:
- name: imageserver
  description: Requests to the imageserver
paths:
  /imageserver:
    get:
      summary: Proxy for the imageserver.
      description: Proxy for the [imageserver API](http://www.hexaplant.com/pixeldragon/3-access-images.html). This is necessary for the frontend. The images at the image server are hashed so that it's possible to restrict access to them. This method checks if the user (if credentials are provided) is authorized to access the image and if it is, it uses the configured secret to create the hash under which image server knows the image. It then accesses the image server proxying all the parameters and proxies back the response.
      tags:
      - imageserver
      parameters:
      - in: query
        name: IIIF
        schema:
          type: string
          required: false
        example: o:440180.tif/full/256,256/0/default.jpg
        description: IIIF request
      responses:
        '200':
          description: Returns the data needed by the IIP-compatible viewers
          content:
            application/json:
              schema:
                type: object
                properties:
                  alerts:
                    type: array
                    items:
                      type: object
                      properties:
                        msg:
                          type: string
                        type:
                          type: string
                  streaming:
                    type: object
                  status:
                    type: number
        '404':
          description: object has not been found
          content:
            application/json:
              schema:
                type: object
  /imageserver/{pid}/status:
    get:
      summary: Get imageserver job status
      description: If imageserver is configured, returns the record from the imageserver job database for the pid specified. Read rights are needed.
      tags:
      - imageserver
      security:
      - basicAuth: []
      parameters:
      - in: path
        name: pid
        schema:
          type: string
          required: true
        description: object pid
      responses:
        '200':
          description: record from the imageserver job database
          content:
            application/json:
              schema:
                type: object
                properties:
                  conversion:
                    type: string
                    example: ok
                  status:
                    type: string
                    example: finished
        '404':
          description: object has not been found
          content:
            application/json:
              schema:
                type: object
  /imageserver/process:
    post:
      summary: Let imageserver process multiple objects.
      description: If an image server is configured, creates a job in the image server's database to process all the pids from the provided list. Needs admin credentials.
      tags:
      - imageserver
      security:
      - basicAuth: []
      parameters:
      - in: query
        name: skipexisting
        schema:
          type: number
          required: false
          enum:
          - 1
        description: Value 1 to skip creating a job for this pid if a job for a pid already exists.
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                pids:
                  type: object
                  properties:
                    pids:
                      type: array
                      items:
                        type: string
                        example: pids
      responses:
        '200':
          description: processed
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    idhash:
                      type: string
                    pid:
                      type: string
                    tmp_hash:
                      type: string
        '404':
          description: Failed
          content:
            application/json:
              schema:
                type: object
  /imageserver/{pid}/process:
    post:
      summary: Post to (re-)process one pid on imageserver.
      description: Post an object to be processed to the imageserver. Needs admin credentials
      tags:
      - imageserver
      security:
      - basicAuth: []
      parameters:
      - in: path
        name: pid
        schema:
          type: string
          required: true
        description: object pid
      - in: query
        name: skipexisting
        schema:
          type: number
          required: false
          enum:
          - 1
        description: Value 1 to skip creating a job for this pid if a job for a pid already exists.
      - in: query
        name: ds
        schema:
          type: string
          required: false
          enum:
          - USERTHUMB
        description: By default, OCTETS is processed. This is a possibility to define another datastream.
      responses:
        '200':
          description: processed
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    idhash:
                      type: string
                    pid:
                      type: string
        '404':
          description: Failed
          content:
            application/json:
              schema:
                type: object
components:
  securitySchemes:
    tokenAuth:
      type: apiKey
      in: header
      name: X-XSRF-TOKEN
    basicAuth:
      type: http
      scheme: basic