openapi: 3.2.0
info:
  title: ScholarSphere Files API
  description: API specification for ScholarSphere
  termsOfService: https://scholarsphere.psu.edu/about
  contact:
    name: ScholarSphere Support
    email: https://scholarsphere.psu.edu/help
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  version: '1.0'
servers:
- url: https://scholarsphere.psu.edu/api/{version}
  description: API endpoint
  variables:
    version:
      description: Version of the API
      enum:
      - v1
      default: v1
tags:
- name: Files
paths:
  /files:
    put:
      summary: Updates a file's metadata
      description: The client can update a file's metadata, such as the results of a virus scan or other async process.
      security:
      - APIKey: []
      requestBody:
        description: Posting updating information for a file after checking for viruses
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/fileMetadata'
            examples:
              novirus:
                summary: No virus was found in the file
                description: Client posts a json object containing the results of the virus check and when it was performed.
                value:
                  id: '1'
                  metadata:
                    virus:
                      status: 'false'
                      scanned_at: '2021-01-25'
              yesvirus:
                summary: A virus was found in the file
                description: Client posts a json object containing a positive virus check and when it was performed.
                value:
                  id: '1'
                  metadata:
                    virus:
                      status: 'true'
                      scanned_at: '2021-01-25'
      responses:
        200:
          description: The file's metadata was successfully updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/successResponse'
              examples:
                summary: The client is not authorized to perform the requested action
                value:
                  message: File was successfully updated
        default:
          $ref: '#/components/responses/defaultPostError'
      tags:
      - Files
      operationId: putFiles
      x-operation-id-source: derived
components:
  schemas:
    id:
      type: object
      properties:
        id:
          type: integer
          example: '1'
    errorResponse:
      required:
      - code
      - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
        errors:
          type: array
          items:
            type: string
    fileMetadata:
      required:
      - id
      properties:
        id:
          $ref: '#/components/schemas/id'
        metadata:
          allOf:
          - $ref: '#/components/schemas/virusCheck'
    virusCheck:
      properties:
        status:
          type: string
          format: boolean
          enum:
          - true
          - false
        scanned_at:
          type: string
          format: date
    successResponse:
      required:
      - message
      properties:
        message:
          type: string
  examples:
    unauthorized:
      summary: The client is not authorized to perform the requested action
      value:
        code: 401
        message: '401: Request not authorized. Please provide a valid API key for access.'
    serverError:
      summary: The server threw some kind of error or exception
      value:
        code: 500
        message: We're sorry, but something went wrong
        errors:
        - NoMethodError
        - undefined method `application' for nil:NilClass
    notFound:
      summary: The requested resource does not exist
      value:
        code: 404
        message: Record not found
    unprocessableEntity:
      summary: The request has missing or incorrect information
      value:
        code: 411
        message: Unable to complete the request
        errors:
        - Sample error from server
  responses:
    defaultPostError:
      description: If the resource can't be created, then there is some kind of error. The client can interpret the responses.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            unauthorized:
              $ref: '#/components/examples/unauthorized'
            notFound:
              $ref: '#/components/examples/notFound'
            unprocessableEntity:
              $ref: '#/components/examples/unprocessableEntity'
            serverError:
              $ref: '#/components/examples/serverError'
  securitySchemes:
    APIKey:
      type: apiKey
      description: Key-based authorization mechanism to the API. A key is obtained fron the ScholarSphere team and is included in the header of all requests.
      name: X_API_KEY
      in: header