openapi: 3.2.0
info:
  title: Peking University Institutional Repository REST Communities API
  description: 'Read-only HTTP/JSON API for the Institutional Repository of Peking University (北京大学机构知识库), operated by the PKU Library at ir.pku.edu.cn on Peking University''s own domain. The deployment runs DSpace repository software, but the service, the host, the handle prefix (20.500.11897) and the record set are the institution''s, and the payloads carry PKU-specific extensions (claim, award4pku, taglist, deptid, deptname) that are not present in stock DSpace — this is an institution-operated deployment, not a hosted vendor tenancy.

    Every path and response shape in this document was captured from live, unauthenticated probes on 2026-08-19. Paths that did not answer are not included.'
  version: '1.0'
  contact:
    name: PKU Institutional Repository
    email: pkuir@lib.pku.edu.cn
    url: https://ir.pku.edu.cn/
  x-operator: institution
  x-operator-evidence: Host ir.pku.edu.cn is under Peking University's own registrable domain pku.edu.cn; OAI-PMH Identify names the repository "Institutional Repository of Peking University" with adminEmail pkuir@lib.pku.edu.cn.
  x-generated: '2026-08-19'
  x-method: probed
  x-source: https://ir.pku.edu.cn/rest/status
servers:
- url: https://ir.pku.edu.cn/rest
  description: Production repository REST API (no authentication required for read paths)
tags:
- name: Communities
  description: Top-level organisational units of the repository (schools, departments, patent and thesis collections).
paths:
  /communities:
    get:
      tags:
      - Communities
      summary: List communities
      operationId: listCommunities
      parameters:
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      - $ref: '#/components/parameters/Expand'
      responses:
        '200':
          description: Array of communities
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Community'
              examples:
                live:
                  externalValue: ../examples/peking-ir-rest-communities-response.json
  /communities/{communityId}:
    get:
      tags:
      - Communities
      summary: Get one community
      operationId: getCommunity
      parameters:
      - name: communityId
        in: path
        required: true
        schema:
          type: integer
        example: 20
      - $ref: '#/components/parameters/Expand'
      responses:
        '200':
          description: Community
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Community'
components:
  parameters:
    Limit:
      name: limit
      in: query
      required: false
      description: Maximum number of records to return.
      schema:
        type: integer
        default: 100
    Expand:
      name: expand
      in: query
      required: false
      description: Comma-separated list of relations to inline. Every response advertises its own legal values in the `expand` array it returns.
      schema:
        type: string
      example: metadata,bitstreams
    Offset:
      name: offset
      in: query
      required: false
      description: Number of records to skip.
      schema:
        type: integer
        default: 0
  schemas:
    Community:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        handle:
          type: string
          example: 20.500.11897/413921
        type:
          type: string
          const: community
        link:
          type: string
        expand:
          type: array
          items:
            type: string
        logo:
          type:
          - string
          - 'null'
        parentCommunity:
          type:
          - object
          - 'null'
        copyrightText:
          type: string
        introductoryText:
          type: string
        shortDescription:
          type: string
        sidebarText:
          type: string
        countItems:
          type: integer
        subcommunities:
          type: array
          items:
            type: object
        collections:
          type: array
          items:
            type: object