openapi: 3.0.2
info:
  title: Discovery bitstreams search 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: search
paths:
  /search:
    get:
      tags:
      - search
      summary: Search items.
      description: Search items.
      operationId: searchItems
      parameters:
      - name: expand
        in: query
        description: Show additional data for the item. Possible values are all, metadata, parentCollection, parentCollectionList, parentCommunityList, bitstreams.
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
          example: metadata
      - name: limit
        in: query
        description: The maximum amount of items shown.
        schema:
          type: integer
          format: int32
      - name: offset
        in: query
        description: The amount of items to skip.
        schema:
          type: integer
          format: int32
      - name: query
        in: query
        description: The search query.
        required: true
        schema:
          type: string
        examples:
          Search items which have a specific value in two or more fields:
            value: dc.identifier.doi:"10.3929/ethz-a-005692772" OR dc.identifier.uri:"http://hdl.handle.net/20.500.11850/154656"
          ? Search item with specific language in dc.language.iso (Because 'it' is a stopword, the query is performed using a mapped search index key)
          : value: iso_keyword=it
      - name: fq
        in: query
        description: Filter queries.
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: sort
        in: query
        description: 'Sort the item results by fieldname|desc; ie: author|desc.'
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      responses:
        200:
          description: successful operation
  /search/authors/{query}:
    get:
      tags:
      - search
      summary: Retrieve a a list of authors that match the search query.
      description: Retrieve a a list of authors that match the search query.
      operationId: getAuthors
      parameters:
      - name: query
        in: path
        description: The query string of the author
        required: true
        schema:
          type: string
      - name: offset
        in: query
        description: The offset of the authors shown.
        schema:
          type: integer
          format: int32
      - name: limit
        in: query
        description: The maximum amount of authors shown.
        schema:
          type: integer
          format: int32
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties: {}
            application/xml:
              schema:
                type: array
                items:
                  type: object
                  properties: {}
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: apikey
externalDocs:
  description: OAS 3 Swagger Documentation
  url: https://apidocs.library.ethz.ch/discovery/v1/