openapi.yml

# Swagger spec for Scholarsphere (see https://swagger.io/specification/)

openapi: "3.0.2"
info:
  title: "ScholarSphere"
  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"

# Listing of the basic model concepts used in the application (see https://swagger.io/specification/#tagObject)
tags:
  - name: "Work"
    description: "The primary unit of content in ScholarSphere"
  - name: "WorkVersion"
    description: "An instance of work, containing descriptive metadata and binary content"
  - name: "Collection"
    description: "A resource with descriptive metadata containing an ordered grouping of works"
  - name: "Actor"
    description: >-
      An identifiable person who has a relationship to a work or collection. They are linked to resources in two ways:
      1) a depositor, linked directly to the resource; or 2) a creator, linked to a resource via an authorship.
      Any given actor will have zero to many authorships.
  - name: "Authorship"
    description: >-
      A person who has authored a resource, either a collection or work. These are listed as "creators" in the
      application. If the person is identifiable, either via a Penn State access id or an Orcid, they will have a
      corresponding linked actor record. If they are not identifiable, there is no linked actor record.

# Paths Object, containing multiple Path Item Objects. Each path item will contain multiple Operation Objects.
# See:
#   https://swagger.io/specification/#pathsObject
#   https://swagger.io/specification/#pathItemObject
#   https://swagger.io/specification/#operationObject
paths:
  /ingest:
    post:
      summary: "Publishes a new work"
      description: >-
        Creates a new work with a single version, and if all the requirements are present, the version will be published
        and publicly available.
      security:
        - APIKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ingest"
      responses:
        200:
          description: "The work was successfully published"
        201:
          description: "The work was created, but not published"
        default:
          $ref: "#/components/responses/defaultPostError"
  /collections:
    post:
      summary: "Creates a new collection"
  /dois:
    get:
      summary: "List of all DOIs"
      description: >-
        Retrieve a dictionary of all DOIs known to Scholarsphere. The keys in
        this dictionary will be the DOI, like `"doi:10.26207/002c-bb83"` and the
        value will be an array of UUIDs of all resources that reference that DOI
      security:
        - APIKey: []
      responses:
        200:
          description: A list of all DOIs
          content: 
            application/json:
              schema:
                $ref: "#/components/schemas/doi_list"
  /dois/{doi}:
    get:
      summary: "Search for a DOI"
      description: >-
        Retrieve a list of resources that mention the given DOI.
      security:
        - APIKey: []
      parameters:
        - name: doi
          in: path
          description: >-
            A DOI name, including the slash ("/"). Just put the slash right in
            the url, like `/dois/10.26207/002c-bb83`
          required: true
          schema:
            type: "string"
            example: "10.26207/002c-bb83"
      responses:
        200:
          description: "The DOI was found in one or more resources"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/doi_response"
        404:
          description: "The DOI was not found in any of ScholarSphere's resources"
  /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"
  /featured_resources:
    post:
      summary: "Adds a new featured resource to the home page"
      security:
        - APIKey: []
      requestBody:
        description: "Given an existing UUID for a resource, feature it on the homepage"
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/featuredResource'
            examples:
              standard:
                summary: "Makes this work a featured work on the homepage"
                description: >-
                  Client posts a json object containing the uuid of the resource they want to have featured.
                value:
                  uuid: 'a0fc525b-0d49-48e0-a385-f86bd13bce4d'
      responses:
        200:
          description: >-
            If the resources has been featured before, or is already featured, it will update with a new timestamp and
            moved to the top of the list.
        201:
          description: >-
            The resource has not been featured before, and a new entry is made in the list of featured resources, moving
            this one to the top.
        default:
          $ref: "#/components/responses/defaultPostError"
  /uploads:
    post:
      summary: "Requests a pre-signed URL to upload a file into ScholarSphere's S3 instance"
      security:
        - APIKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/uploads"

# Array of Schema Objects used to define the concepts/models (see https://swagger.io/specification/#schemaObject)
components:
  schemas:
    doi_list:
      type: "object"
      additionalProperties:
        type: "array"
        description: "a list of resource UUIDs"
        items:
          type: "string"
          description: "a resource UUID"
          example: "a0fc525b-0d49-48e0-a385-f86bd13bce4d"
      example:
        "doi:10.26207/002c-bb83":
          - "a0fc525b-0d49-48e0-a385-f86bd13bce4d"
          - "146a74e3-ae66-4802-b5f8-471bcac80d58"
        "doi:10.18113/dmnf-6dzs":
          - "87287b53-76be-424e-b202-bc6d521c841b"
    doi_response:
      type: "array"
      items:
        type: "object"
        properties:
          url: 
            type: "string"
            format: "uri"
            example: "/resources/a0fc525b-0d49-48e0-a385-f86bd13bce4d"
            description: "path to a Scholarsphere resource"
    uuid:
      type: "object"
      properties:
        uuid:
          type: "string"
          example: "a0fc525b-0d49-48e0-a385-f86bd13bce4d"
    id:
      type: "object"
      properties:
        id:
          type: "integer"
          example: '1'
    metadata:
      type: "object"
      required:
        - "title"
        - "work_type"
        - "description"
        - "published_date"
        - "creators"
        - "rights"
        - "visibility"
      properties:
        title:
          type: "string"
          example: "Classifying Independent Hybridity"
        work_type:
          type: "string"
          enum:
            - article
            - audio
            - book
            - collection
            - conference_proceeding
            - dataset
            - image
            - journal
            - map_or_cartographic_material
            - masters_culminating_experience
            - other
            - part_of_book
            - poster
            - presentation
            - professional_doctoral_culminating_experience
            - project
            - report
            - research_paper
            - software_or_program_code
            - video
          example: "dataset"
        description:
          type: "string"
          example: >-
            Anaesthesiology anthropology chaology craniology ecology endocrinology epileptology gnomonics ichthyology
            linguistics mammalogy mazology nasology nematology neurobiology palaeontology psychopathology pterylology
            textology toponymics. Aerostatics anemology avionics diplomatology euthenics geochemistry historiography
            historiology hydrology hydrometeorology hygiastics iatromathematics lexigraphy martyrology metallogeny
            neonatology numismatics oikology patrology pestology photobiology psychobiology psychology sphagnology
            stemmatology threpsology ufology vinology. Arctophily astrophysics carcinology dactylology electrology
            genealogy horography hydrobiology immunopathology lexigraphy molinology nidology paidonosology
            palaeopedology venereology.
        published_date:
          type: "string"
          format: "date"
          example: "2020-10-31"
          description: >-
            EDTF date formats are also supported. See https://www.loc.gov/standards/datetime/
        publisher_statement:
          type: "string"
          example: >-
            This is a pre-print from Joe Publisher, Inc. We are not responsible for anything.
          description: >-
            This is also referred to as a "set statement" and is often a required part for Open Access articles.
        keyword:
          type: "array"
          items:
            type: "string"
          example: ["optics", "quantum physics", "fake paper names"]
        subtitle:
          type: "string"
          example: "Quantum Optics and/in the Clan"
        publisher:
          type: "array"
          items:
            type: "string"
        subject:
          type: "array"
          items:
            type: "string"
        language:
          type: "array"
          items:
            type: "string"
        identifier:
          type: "array"
          items:
            type: "string"
        based_near:
          type: "array"
          items:
            type: "string"
        related_url:
          type: "array"
          items:
            type: "string"
        sub_work_type:
          type: "string"
          enum:
            - Capstone Course Work Product
            - Capstone Project
            - Culminating Research Project
            - Doctor of Nursing Practice Project
            - Integrative Doctoral Research Project
            - Praxis Project
            - Public Performance
            - Scholarly Paper/Essay (MA/MS)
          example: "Capstone Project"
        program:
          type: "string"
          example: "Acoustics"
        degree:
          type: "string"
          enum:
            - Doctor of Education
            - Doctor of Musical Arts
            - Doctor of Nursing Practice
            - Doctor of Public Health
            - Doctor of Philosophy
            - Master of Arts
            - Master of Science
          example: "Master of Science"
        source:
          type: "array"
          items:
            type: "string"
        creators:
          type: "array"
          items:
            $ref: "#/components/schemas/creator"
        contributor:
          type: "array"
          items:
            type: "string"
          example: ["Dr. Phyllis Abracadabra", "Harry L. Snethers"]
        rights:
          type: "string"
          enum:
            - https://creativecommons.org/licenses/by/4.0/
            - https://creativecommons.org/licenses/by-sa/4.0/
            - https://creativecommons.org/licenses/by-nc/4.0/
            - https://creativecommons.org/licenses/by-nd/4.0/
            - https://creativecommons.org/licenses/by-nc-nd/4.0/
            - https://creativecommons.org/licenses/by-nc-sa/4.0/
            - http://creativecommons.org/publicdomain/mark/1.0/
            - http://creativecommons.org/publicdomain/zero/1.0/
            - https://rightsstatements.org/page/InC/1.0/
            - http://www.apache.org/licenses/LICENSE-2.0
            - https://www.gnu.org/licenses/gpl.html
            - https://opensource.org/licenses/MIT
            - https://opensource.org/licenses/BSD-3-Clause
          example: "https://creativecommons.org/licenses/by/4.0/"
        visibility:
          type: "string"
          enum:
            - open
            - authenticated
        embargoed_until:
          type: "string"
          format: "date"
        version_name:
          type: "string"
          example: "1.0.0"
          description: "Must be in semantic version format. See https://semver.org/"
        doi:
          type: "string"
          example: "doi:10.26207/002c-bb83"
          description: >-
            A DOI minted under Scholarsphere's current prefix, 10.26207. If you have another DOI that was previously
            supplied by a publisher or someone else, that can be put into the identifier field.
    creator:
      type: "object"
      required:
        - "display_name"
      properties:
        display_name:
          type: "string"
          example: "Dr. Pat Researcher"
        surname:
          type: "string"
          example: "Researcher"
        given_name:
          type: "string"
          example: "Pat"
        email:
          type: "string"
          example: "pat@example.com"
        psu_id:
          type: "string"
          example: "axb123"
        orcid: 
          type: "string"
          example: "0000-0000-1234-123X"
    ingest:
      type: "object"
      required:
        - "metadata"
        - "depositor"
        - "content"
      properties:
        metadata:
          $ref: "#/components/schemas/metadata"
        content:
          type: "array"
          description: >-
            Files that have been uploaded to S3 in a previous step. The location information for each one, as well as
            their original names and mime types, is included here.
          items:
            $ref: "#/components/schemas/uploadedFile"
        depositor:
          type: "string"
          exmample: "axc123"
          description: >-
            The Penn State access of the person who is depositing the work. This is typically the same person who is the
            creator, but not always. There is no restriction regarding who the depositor is other than they must have an
            active account in Penn State's identity management system.
        permissions:
          $ref: "#/components/schemas/permissions" 
    uploads:
      type: "object"
      required:
        - "extension"
        - "content_md5"
      properties:
        extension:
          type: "string"
          description: >-
            Three-letter file extension of the file your are requesting to upload into S3. This is used to created a
            unique filename for the file in S3.
        content_md5:
          type: "string"
          description: >-
            Binary encoded md5 checksum of the file you are requesting to upload into S3. This is required so that we
            can verify the integrity of the file when it is uploaded into S3.
    uploadedFile:
      type: "object"
    permissions:
      type: "object"
      description: >-
        Additional permissions for the work such as users or groups that can edit work. By default, only the depositor
        may edit the work after it has been uploaded.
    featuredResource:
      allOf:
        - $ref: "#/components/schemas/uuid"
        - type: 'object'
          required:
            - 'uuid'
    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"
    successResponse:
      required:
        - message
      properties:
        message:
          type: string
    virusCheck:
      properties:
        status:
          type: "string"
          format: 'boolean'
          enum:
            - true
            - false
        scanned_at:
          type: "string"
          format: 'date'
  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"
  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"
  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."
    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"
    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"