openapi: 3.0.3
info:
  title: WIReDSpace DSpace REST API
  description: >-
    REST API for WIReDSpace, the University of the Witwatersrand institutional
    repository, running DSpace 9.2. The API serves a HAL/JSON root document at
    /server/api and exposes read access to communities, collections, items,
    bundles, bitstreams, and discovery/browse endpoints. This specification
    documents the public, anonymously-readable read surfaces verified live
    against the deployment; write, workflow, and administrative endpoints exist
    in DSpace but require authentication and are not enumerated here.
  version: "9.2"
  contact:
    name: Wits Open Scholarship, Library
    email: openscholarship.library@wits.ac.za
    url: https://wiredspace.wits.ac.za/
  license:
    name: DSpace BSD License
    url: https://github.com/DSpace/DSpace/blob/main/LICENSE
servers:
  - url: https://wiredspace.wits.ac.za/server/api
    description: WIReDSpace production DSpace 9.2 REST server
tags:
  - name: Root
    description: HAL/JSON API root document
  - name: Communities
    description: Top-level and sub-community containers
  - name: Collections
    description: Collections of items within communities
  - name: Items
    description: Repository items (records)
  - name: Discovery
    description: Browse and search/discovery endpoints
paths:
  /:
    get:
      tags: [Root]
      summary: API root document
      description: >-
        Returns the DSpace HAL/JSON root document, including dspaceVersion,
        dspaceName, and an _links map of all available endpoints.
      operationId: getRoot
      responses:
        "200":
          description: HAL/JSON root document
          content:
            application/hal+json:
              schema:
                $ref: "#/components/schemas/Root"
  /core/communities:
    get:
      tags: [Communities]
      summary: List communities
      description: Returns a paginated HAL collection of top-level communities.
      operationId: getCommunities
      parameters:
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/Size"
      responses:
        "200":
          description: Paginated list of communities
          content:
            application/hal+json:
              schema:
                $ref: "#/components/schemas/CommunityPage"
  /core/communities/{uuid}:
    get:
      tags: [Communities]
      summary: Get a community by UUID
      operationId: getCommunity
      parameters:
        - $ref: "#/components/parameters/Uuid"
      responses:
        "200":
          description: A single community
          content:
            application/hal+json:
              schema:
                $ref: "#/components/schemas/Community"
        "404":
          description: Community not found
  /core/collections:
    get:
      tags: [Collections]
      summary: List collections
      operationId: getCollections
      parameters:
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/Size"
      responses:
        "200":
          description: Paginated list of collections
          content:
            application/hal+json:
              schema:
                $ref: "#/components/schemas/DSpaceObjectPage"
  /core/collections/{uuid}:
    get:
      tags: [Collections]
      summary: Get a collection by UUID
      operationId: getCollection
      parameters:
        - $ref: "#/components/parameters/Uuid"
      responses:
        "200":
          description: A single collection
          content:
            application/hal+json:
              schema:
                $ref: "#/components/schemas/DSpaceObject"
        "404":
          description: Collection not found
  /core/items/{uuid}:
    get:
      tags: [Items]
      summary: Get an item by UUID
      description: >-
        Returns a single repository item. Anonymous access is governed by the
        item's access policies; restricted items return 401/403.
      operationId: getItem
      parameters:
        - $ref: "#/components/parameters/Uuid"
      responses:
        "200":
          description: A single item
          content:
            application/hal+json:
              schema:
                $ref: "#/components/schemas/DSpaceObject"
        "401":
          description: Authentication required for this item
        "404":
          description: Item not found
  /discover/browses:
    get:
      tags: [Discovery]
      summary: List browse indexes
      description: Returns the configured discovery browse indexes (e.g. by title, author, subject, date issued).
      operationId: getBrowses
      responses:
        "200":
          description: Browse indexes
          content:
            application/hal+json:
              schema:
                $ref: "#/components/schemas/DSpaceObjectPage"
  /discover/search/objects:
    get:
      tags: [Discovery]
      summary: Search discovery objects
      description: Full-text and faceted search across indexed DSpace objects.
      operationId: searchObjects
      parameters:
        - name: query
          in: query
          description: Search query string
          required: false
          schema:
            type: string
        - name: dsoType
          in: query
          description: Restrict results to a DSpace object type (community, collection, item)
          required: false
          schema:
            type: string
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/Size"
      responses:
        "200":
          description: Search result page
          content:
            application/hal+json:
              schema:
                $ref: "#/components/schemas/DSpaceObjectPage"
components:
  parameters:
    Uuid:
      name: uuid
      in: path
      required: true
      description: The UUID of the DSpace object
      schema:
        type: string
        format: uuid
    Page:
      name: page
      in: query
      required: false
      description: Zero-based page index
      schema:
        type: integer
        minimum: 0
        default: 0
    Size:
      name: size
      in: query
      required: false
      description: Page size
      schema:
        type: integer
        minimum: 1
        default: 20
  schemas:
    Root:
      type: object
      properties:
        dspaceUI:
          type: string
          format: uri
          example: https://wiredspace.wits.ac.za
        dspaceName:
          type: string
          example: WIReDSpace
        dspaceServer:
          type: string
          format: uri
          example: https://wiredspace.wits.ac.za/server
        dspaceVersion:
          type: string
          example: DSpace 9.2
        type:
          type: string
          example: root
        _links:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/Link"
    MetadataValue:
      type: object
      properties:
        value:
          type: string
        language:
          type: string
          nullable: true
        authority:
          type: string
          nullable: true
        confidence:
          type: integer
        place:
          type: integer
    Community:
      type: object
      properties:
        id:
          type: string
          format: uuid
        uuid:
          type: string
          format: uuid
        name:
          type: string
        handle:
          type: string
          example: "10539/38213"
        metadata:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: "#/components/schemas/MetadataValue"
        archivedItemsCount:
          type: integer
        type:
          type: string
          example: community
        _links:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/Link"
    DSpaceObject:
      type: object
      properties:
        id:
          type: string
          format: uuid
        uuid:
          type: string
          format: uuid
        name:
          type: string
        handle:
          type: string
        metadata:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: "#/components/schemas/MetadataValue"
        type:
          type: string
        _links:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/Link"
    Link:
      type: object
      properties:
        href:
          type: string
          format: uri
    PageInfo:
      type: object
      properties:
        size:
          type: integer
        totalElements:
          type: integer
        totalPages:
          type: integer
        number:
          type: integer
    CommunityPage:
      type: object
      properties:
        _embedded:
          type: object
          properties:
            communities:
              type: array
              items:
                $ref: "#/components/schemas/Community"
        _links:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/Link"
        page:
          $ref: "#/components/schemas/PageInfo"
    DSpaceObjectPage:
      type: object
      properties:
        _embedded:
          type: object
        _links:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/Link"
        page:
          $ref: "#/components/schemas/PageInfo"