openapi: 3.0.2
info:
  title: Discovery bitstreams communities API
  description: "The Discovery REST API provides access to over 30 million books, images, series, journals, and other materials from the ETH Library's Discovery Portal. \n\n➜ [OAS 3 Swagger Documentation](https://eth-library.github.io/apiplatform-swagger/discovery/v1/)\n\n➜ [ETH Library @ swisscovery Application](https://eth.swisscovery.slsp.ch/)"
  version: 1.0.2
  termsOfService: https://developer.library.ethz.ch/terms
  contact:
    name: API Management ETH Library
    email: api@library.ethz.ch
    url: https://library.ethz.ch
  license:
    url: https://developer.library.ethz.ch/terms
    name: Bibliographic metadata that are not specifically marked are free for general use (Public Domain). Documents, images or other digital objects linked in metadata may be subject to other copyright restrictions. Whenever possible, the licence of the referenced digital objects is indicated in the metadata. In case of doubt, the licence can be inquired at api@library.ethz.ch.
servers:
- url: https://api.library.ethz.ch/discovery/v1/
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: communities
paths:
  /communities:
    get:
      tags:
      - communities
      summary: Retrieve a list of communities.
      description: Retrieve a list of communities.
      operationId: getCommunities
      parameters:
      - name: expand
        in: query
        description: Show additional data for the community.
        style: form
        explode: true
        schema:
          type: string
          items:
            type: string
          enum:
          - all
          - collections
          - parentCommunity
          - parentCommunityList
          - subCommunities
          - logo
      - name: limit
        in: query
        description: The maximum amount of communities shown.
        schema:
          type: integer
          format: int32
      - name: offset
        in: query
        description: The amount of communities to skip.
        schema:
          type: integer
          format: int32
      - name: userIP
        in: query
        schema:
          type: string
      - name: userAgent
        in: query
        schema:
          type: string
      - name: xforwardedfor
        in: query
        schema:
          type: string
      responses:
        200:
          description: successful operation
  /communities/top-communities:
    get:
      tags:
      - communities
      summary: Retrieve a list of top communities.
      description: Retrieve a list of top communities.
      operationId: getTopCommunities
      parameters:
      - name: expand
        in: query
        description: Show additional data for the community.
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
          enum:
          - all
          - collections
          - parentCommunity
          - parentCommunityList
          - subCommunities
          - logo
      - name: limit
        in: query
        description: The maximum amount of communities shown.
        schema:
          type: integer
          format: int32
      - name: offset
        in: query
        description: The amount of communities to skip.
        schema:
          type: integer
          format: int32
      - name: userIP
        in: query
        schema:
          type: string
      - name: userAgent
        in: query
        schema:
          type: string
      - name: xforwardedfor
        in: query
        schema:
          type: string
      responses:
        200:
          description: successful operation
  /communities/{community_id}:
    get:
      tags:
      - communities
      summary: Retrieve a single community by using the internal DSpace community identifier.
      description: Retrieve a single community by using the internal DSpace community identifier.
      operationId: getCommunity
      parameters:
      - name: community_id
        in: path
        description: The identifier of the community.
        required: true
        schema:
          type: integer
          format: int32
      - name: expand
        in: query
        description: Show additional data for the community.
        style: form
        explode: true
        schema:
          type: string
          items:
            type: string
          enum:
          - all
          - collections
          - parentCommunity
          - parentCommunityList
          - subCommunities
          - logo
      - name: userIP
        in: query
        schema:
          type: string
      - name: userAgent
        in: query
        schema:
          type: string
      - name: xforwardedfor
        in: query
        schema:
          type: string
      responses:
        200:
          description: successful operation
  /communities/{community_id}/collections:
    get:
      tags:
      - communities
      summary: Retrieve a list of collections in a community by using the internal DSpace community identifier.
      description: Retrieve a list of collections in a community by using the internal DSpace community identifier.
      operationId: getCommunityCollections
      parameters:
      - name: community_id
        in: path
        description: The identifier of the community.
        required: true
        schema:
          type: integer
          format: int32
      - name: expand
        in: query
        description: Show additional data for the collection.
        style: form
        explode: true
        schema:
          type: string
          items:
            type: string
          enum:
          - all
          - items
          - parentCommunity
          - parentCommunityList
          - license
          - logo
      - name: limit
        in: query
        description: The maximum amount of collections shown.
        schema:
          type: integer
          format: int32
      - name: offset
        in: query
        description: The amount of collections to skip.
        schema:
          type: integer
          format: int32
      - name: userIP
        in: query
        schema:
          type: string
      - name: userAgent
        in: query
        schema:
          type: string
      - name: xforwardedfor
        in: query
        schema:
          type: string
      responses:
        200:
          description: successful operation
  /communities/{community_id}/communities:
    get:
      tags:
      - communities
      summary: Retrieve a list of subcommunities in a community by using the internal DSpace community identifier.
      description: Retrieve a list of subcommunities in a community by using the internal DSpace community identifier.
      operationId: getCommunityCommunities
      parameters:
      - name: community_id
        in: path
        description: The identifier of the community.
        required: true
        schema:
          type: integer
          format: int32
      - name: expand
        in: query
        description: Show additional data for the community.
        style: form
        explode: true
        schema:
          type: string
          items:
            type: string
          enum:
          - all
          - collections
          - parentCommunity
          - parentCommunityList
          - subCommunities
          - logo
      - name: limit
        in: query
        description: The maximum amount of communities shown.
        schema:
          type: integer
          format: int32
      - name: offset
        in: query
        description: The amount of communities to skip.
        schema:
          type: integer
          format: int32
      - name: userIP
        in: query
        schema:
          type: string
      - name: userAgent
        in: query
        schema:
          type: string
      - name: xforwardedfor
        in: query
        schema:
          type: string
      responses:
        200:
          description: successful operation
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: apikey
externalDocs:
  description: OAS 3 Swagger Documentation
  url: https://apidocs.library.ethz.ch/discovery/v1/