Peking University Items API

openapi: 3.2.0
info:
  title: Peking University Institutional Repository REST Items 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.
  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: Items
  description: Individual repository records — articles, theses, patents — and their metadata and bitstreams.
paths:
  /collections/{collectionId}/items:
    get:
      tags:
      - Items
      summary: List the items in a collection
      operationId: listCollectionItems
      parameters:
      - name: collectionId
        in: path
        required: true
        schema:
          type: integer
        example: 138
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      - $ref: '#/components/parameters/Expand'
      responses:
        '200':
          description: Array of items
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Item'
  /items:
    get:
      tags:
      - Items
      summary: List items
      operationId: listItems
      parameters:
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      - $ref: '#/components/parameters/Expand'
      responses:
        '200':
          description: Array of items
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Item'
              examples:
                live:
                  externalValue: ../examples/peking-ir-rest-items-response.json
  /items/{itemId}/metadata:
    get:
      tags:
      - Items
      summary: Get the Dublin Core metadata of an item
      description: Returns the item's flat Dublin Core key/value/language triples. Verified 200 on 2026-08-19 for item 3.
      operationId: getItemMetadata
      parameters:
      - name: itemId
        in: path
        required: true
        schema:
          type: integer
        example: 3
      responses:
        '200':
          description: Array of metadata entries
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MetadataEntry'
  /items/{itemId}/bitstreams:
    get:
      tags:
      - Items
      summary: List the files attached to an item
      operationId: getItemBitstreams
      parameters:
      - name: itemId
        in: path
        required: true
        schema:
          type: integer
        example: 3
      responses:
        '200':
          description: Array of bitstreams
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Bitstream'
  /handle/{prefix}/{suffix}:
    get:
      tags:
      - Items
      summary: Resolve a Handle to the object it identifies
      description: Resolves a Handle.Net identifier under the repository's own prefix 20.500.11897 to the community, collection or item it names. Verified 200 on 2026-08-19 for handle 20.500.11897/69.
      operationId: resolveHandle
      parameters:
      - name: prefix
        in: path
        required: true
        schema:
          type: string
        example: 20.500.11897
      - name: suffix
        in: path
        required: true
        schema:
          type: string
        example: '69'
      responses:
        '200':
          description: The resolved object
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/Item'
                - $ref: '#/components/schemas/Collection'
                - $ref: '#/components/schemas/Community'
components:
  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
    MetadataEntry:
      type: object
      properties:
        key:
          type: string
          example: dc.contributor.author
        value:
          type: string
        language:
          type:
          - string
          - 'null'
          example: zh_CN
    Collection:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        handle:
          type: string
        type:
          type: string
          const: collection
        link:
          type: string
        expand:
          type: array
          items:
            type: string
        numberItems:
          type: integer
        license:
          type:
          - string
          - 'null'
        copyrightText:
          type: string
        introductoryText:
          type: string
        shortDescription:
          type: string
        sidebarText:
          type: string
        deptid:
          type: string
          description: PKU extension — the owning department identifier.
        deptname:
          type: string
          description: PKU extension — the owning department name.
    Item:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        handle:
          type: string
        type:
          type: string
          const: item
        link:
          type: string
        expand:
          type: array
          items:
            type: string
        lastModified:
          type: string
          example: '2015-09-25 09:47:29.576'
        itemID:
          type: integer
        claim:
          type:
          - string
          - 'null'
          description: PKU extension — author claim state for the record.
        award4pku:
          type:
          - string
          - 'null'
          description: PKU extension — award/recognition marker.
        claim_list:
          type:
          - array
          - 'null'
          items:
            type: object
        claim_list_size:
          type: integer
        taglist:
          type:
          - array
          - 'null'
          items:
            type: object
          description: PKU extension — local subject tags.
    Bitstream:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        handle:
          type:
          - string
          - 'null'
        type:
          type: string
          const: bitstream
        link:
          type: string
        expand:
          type: array
          items:
            type: string
        bundleName:
          type: string
          example: ORIGINAL
        description:
          type:
          - string
          - 'null'
  parameters:
    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
    Limit:
      name: limit
      in: query
      required: false
      description: Maximum number of records to return.
      schema:
        type: integer
        default: 100
    Offset:
      name: offset
      in: query
      required: false
      description: Number of records to skip.
      schema:
        type: integer
        default: 0