openapi: 3.0.1
info:
  title: bookdatabase.io
  version: v1
  termsOfService: https://bookdatabase.io/terms-of-service.html

servers:
  - url: https://api.bookdatabase.io/v1

paths:
  "/authors/{id}":
    get:
      tags:
      - Authors
      description: Gets a single author by their id.
      parameters:
      - name: id
        in: path
        required: true
        description: The id of the author.
        schema:
          $ref: "#/components/schemas/ResourceId"
      - $ref: "#/components/parameters/IncludeRelationships"
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Author"
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No author with the specified id exists
        '500':
          description: Internal server error
  "/authors/random":
    get:
      tags:
      - Authors
      description: Gets a random single author.
      parameters:
      - $ref: "#/components/parameters/IncludeRelationships"
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Author"
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
  "/authors":
    get:
      tags:
      - Authors
      description: |
        Gets all authors that fit the search criteria.
        At least one of "searchQuery", "bookId" or "editionId" must be specified.
        If more than one search criteria is specified, only the authors that fit all of them are returned.
        Full-text searchable author properties: name, alternative names.
        The results are paged.
      parameters:
        - $ref: "#/components/parameters/SearchQuery"
        - $ref: "#/components/parameters/SearchMode"
        - name: bookId
          in: query
          required: false
          description: The id of the book that the authors must be an author of.
          schema:
            $ref: "#/components/schemas/ResourceId"
        - name: editionId
          in: query
          required: false
          description: The id of the edition that the authors must be an author of.
          schema:
            $ref: "#/components/schemas/ResourceId"
        - name: sortOrder
          in: query
          required: false
          description: |
            The order in which the authors are returned.
            SearchRelevanceDescending may only be used if a searchQuery is specified.
          schema:
            type: string
            enum:
            - NameAlphabetic
            - NameReverseAlphabetic
            - SearchRelevanceDescending
            #- NumberOfWorksHighToLow
            #- NumberOfWorksLowToHigh
            #- NumberOfEditionsHighToLow
            #- NumberOfEditionsLowToHigh
            maxLength: 128
            default: NameAlphabetic
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/ContinuationToken"
        - $ref: "#/components/parameters/IncludeRelationships"
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                description: A page of authors.
                allOf:
                  - $ref: "#/components/schemas/HalPageLinks"
                  - type: object
                    nullable: false
                    properties:
                      _embedded:
                        type: object
                        nullable: false
                        properties:
                          authors:
                            type: array
                            nullable: false
                            items:
                              $ref: "#/components/schemas/Author"
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
  "/books/{id}":
    get:
      tags:
      - Books
      description: Gets a single book by its id.
      parameters:
      - name: id
        in: path
        required: true
        description: The id of the book.
        schema:
          $ref: "#/components/schemas/ResourceId"
      - $ref: "#/components/parameters/IncludeRelationships"
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Book"
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No book with the specified id exists
        '500':
          description: Internal server error
  "/books/random":
    get:
      tags:
      - Books
      description: Gets a random single book.
      parameters:
      - $ref: "#/components/parameters/IncludeRelationships"
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Book"
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
  "/books":
    get:
      tags:
      - Books
      description: |
        Gets all books that fit the search criteria.
        At least one of "searchQuery", "authorId", "subjectId", "placeId", "timeId" or "personId" must be specified.
        If more than one search criteria is specified, only the books that fit all of them are returned.
        Full-text searchable book properties: title.
        The results are paged.
      parameters:
      - $ref: "#/components/parameters/SearchQuery"
      - $ref: "#/components/parameters/SearchMode"
      - name: authorId
        in: query
        required: false
        description: The id of the author that the books must be written by.
        schema:
          $ref: "#/components/schemas/ResourceId"
      - name: subjectId
        in: query
        required: false
        description: The id of the subjects that the books contents must handle.
        schema:
          $ref: "#/components/schemas/ResourceId"
      - name: placeId
        in: query
        required: false
        description: The id of the place that the books contents must handle.
        schema:
          $ref: "#/components/schemas/ResourceId"
      - name: timeId
        in: query
        required: false
        description: The id of the time that the books contents must handle.
        schema:
          $ref: "#/components/schemas/ResourceId"
      - name: personId
        in: query
        required: false
        description: The id of the person that the books contents must handle.
        schema:
          $ref: "#/components/schemas/ResourceId"
      - name: sortOrder
        in: query
        required: false
        description: |
          The order in which the books are returned.
          SearchRelevanceDescending may only be used if a searchQuery is specified.
        schema:
          type: string
          enum:
          - TitleAlphabetic
          - TitleReverseAlphabetic
          - SearchRelevanceDescending
          #- FirstPublishDateNewToOld
          #- FirstPublishDateOldToNew
          #- NumberOfAuthorsHighToLow
          #- NumberOfAuthorsLowToHigh
          #- NumberOfEditionsHighToLow
          #- NumberOfEditionsLowToHigh
          maxLength: 128
          default: TitleAlphabetic
      - $ref: "#/components/parameters/PageSize"
      - $ref: "#/components/parameters/ContinuationToken"
      - $ref: "#/components/parameters/IncludeRelationships"
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                description: A page of books.
                allOf:
                  - $ref: "#/components/schemas/HalPageLinks"
                  - type: object
                    nullable: false
                    properties:
                      _embedded:
                        type: object
                        nullable: false
                        properties:
                          books:
                            type: array
                            nullable: false
                            items:
                              $ref: "#/components/schemas/Book"
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
  "/editions/{id}":
    get:
      tags:
      - Editions
      description: Gets a single edition by its id.
      parameters:
      - name: id
        in: path
        required: true
        description: The id of the edition.
        schema:
          $ref: "#/components/schemas/ResourceId"
      - $ref: "#/components/parameters/IncludeRelationships"
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Edition"
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No author with the specified id exists
        '500':
          description: Internal server error
  "/editions/random":
    get:
      tags:
      - Editions
      description: Gets a random single edition.
      parameters:
      - $ref: "#/components/parameters/IncludeRelationships"
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Edition"
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
  "/editions":
    get:
      tags:
      - Editions
      description: |
        Gets all editions that fit the search criteria.
        At least one of "searchQuery", "isbn", "bookId", "authorId", "genreId", "languageId", "publisherId", "publishPlaceId" must be specified.
        If more than one search criteria is specified, only the editions that fit all of them are returned.
        Full-text searchable author properties: title, alternate titles.
        The results are paged.
      parameters:
      - $ref: "#/components/parameters/SearchQuery"
      - $ref: "#/components/parameters/SearchMode"
      - name: isbn
        in: query
        required: false
        description: |
          The ISBN (ISBN-10 or ISBN-13) that the editions must have.
          Spaces (" "), hyphens (-) and single quotes (') are ignored.
          E.g. "9780825620492" or "082562049X".
        schema:
          type: string
          maxLength: 32
      - name: authorId
        in: query
        required: false
        description: The id of the author that the editions must be written by.
        schema:
          $ref: "#/components/schemas/ResourceId"
      - name: languageId
        in: query
        required: false
        description: The id of the language that the editions must be written in.
        schema:
          $ref: "#/components/schemas/ResourceId"
      - name: publisherId
        in: query
        required: false
        description: The id of the publisher that the editions must have been published by.
        schema:
          $ref: "#/components/schemas/ResourceId"
      - name: publishPlaceId
        in: query
        required: false
        description: The id of the place that the editions must have been published at.
        schema:
          $ref: "#/components/schemas/ResourceId"
      - name: genreId
        in: query
        required: false
        description: The id of the genre that the editions must belong to.
        schema:
          $ref: "#/components/schemas/ResourceId"
      - name: bookId
        in: query
        required: false
        description: The id of the book that the editions must be an edition of.
        schema:
          $ref: "#/components/schemas/ResourceId"
      - name: sortOrder
        in: query
        required: false
        description: |
          The order in which the editions are returned.
          SearchRelevanceDescending may only be used if a searchQuery is specified.
        schema:
          type: string
          enum:
          - TitleAlphabetic
          - TitleReverseAlphabetic
          - SearchRelevanceDescending
          #- NumberOfAuthorsHighToLow
          #- NumberOfAuthorsLowToHigh
          #- PublishDateNewToOld
          #- PublishDateOldToNew
          maxLength: 128
          default: TitleAlphabetic
      - $ref: "#/components/parameters/PageSize"
      - $ref: "#/components/parameters/ContinuationToken"
      - $ref: "#/components/parameters/IncludeRelationships"
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                description: A page of editions.
                allOf:
                  - $ref: "#/components/schemas/HalPageLinks"
                  - type: object
                    nullable: false
                    properties:
                      _embedded:
                        type: object
                        nullable: false
                        properties:
                          editions:
                            type: array
                            nullable: false
                            items:
                              $ref: "#/components/schemas/Edition"
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
  "/genres/{id}":
    get:
      tags:
      - Genres
      description: Gets a single genre by its id.
      parameters:
      - name: id
        in: path
        required: true
        description: The id of the genre.
        schema:
          $ref: "#/components/schemas/ResourceId"
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Genre"
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No genre with the specified id exists
        '500':
          description: Internal server error
  "/genres/random":
    get:
      tags:
      - Genres
      description: Gets a random single genre.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Genre"
        '500':
          description: Internal server error
  "/genres":
    get:
      tags:
      - Genres
      description: |
        Gets all genres.
        Full-text search is not (yet) supported.
        The results are paged.
      parameters:
      - name: sortOrder
        in: query
        required: false
        description: The order in which the genres are returned.
        schema:
          type: string
          enum:
          - NameAlphabetic
          - NameReverseAlphabetic
          #- NumberOfEditionsHighToLow
          #- NumberOfEditionsLowToHigh
          maxLength: 128
          default: NameAlphabetic
      - $ref: "#/components/parameters/PageSize"
      - $ref: "#/components/parameters/ContinuationToken"
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                description: A page of genres.
                allOf:
                  - $ref: "#/components/schemas/HalPageLinks"
                  - type: object
                    nullable: false
                    properties:
                      _embedded:
                        type: object
                        nullable: false
                        properties:
                          genres:
                            type: array
                            nullable: false
                            items:
                              $ref: "#/components/schemas/Genre"
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
  "/images/{id}/contentUrl":
    get:
      tags:
      - Images
      description: |
        Gets the content URL of an image by its id.
        Every content URL returned is unique and only valid for 5 minutes after this endpoint was called.
      parameters:
      - name: id
        in: path
        required: true
        description: The id of the image.
        schema:
          $ref: "#/components/schemas/ResourceId"
      responses:
        '302':
          description: |
            Success.
            The response is empty and does not contain the image itself. Instead, the "Location" response header contains the URL of the image.
            Every content URL returned is unique and only valid for 5 minutes after this endpoint was called.
          headers:
            Location:
              schema:
                type: string
                maxLength: 2048
                example: https://bookdatabaseprdcus.blob.core.windows.net/images/10e1cd03-9099-ec11-8487-704d7b630b44.jpg?sv=2019-02-02&sr=b&sig=EO6EmOzrKH7zRF05tBE7388RoO26IBcGFwpf1%2FLYyQQ%3D&st=2023-01-08T20%3A47%3A07Z&se=2023-01-08T21%3A07%3A07Z&sp=r
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No image with the specified id is available
        '500':
          description: Internal server error
  "/languages/{id}":
    get:
      tags:
      - Languages
      description: Gets a single language by its id.
      parameters:
      - name: id
        in: path
        required: true
        description: The id of the language.
        schema:
          $ref: "#/components/schemas/ResourceId"
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Language"
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No language with the specified id exists
        '500':
          description: Internal server error
  "/languages/random":
    get:
      tags:
      - Languages
      description: Gets a random single language.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Language"
        '500':
          description: Internal server error
  "/languages":
    get:
      tags:
      - Languages
      description: |
        Gets all languages.
        Full-text search is not (yet) supported.
        The results are paged.
      parameters:
      - name: sortOrder
        in: query
        required: false
        description: The order in which the languages are returned.
        schema:
          type: string
          enum:
          - EnglishNameAlphabetic
          - EnglishNameReverseAlphabetic
          - Iso639CodeAlphabetic
          - Iso639CodeReverseAlphabetic
          #- NumberOfEditionsHighToLow
          #- NumberOfEditionsLowToHigh
          maxLength: 128
          default: Iso639CodeAlphabetic
      - $ref: "#/components/parameters/PageSize"
      - $ref: "#/components/parameters/ContinuationToken"
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                description: A page of languages.
                allOf:
                  - $ref: "#/components/schemas/HalPageLinks"
                  - type: object
                    nullable: false
                    properties:
                      _embedded:
                        type: object
                        nullable: false
                        properties:
                          languages:
                            type: array
                            nullable: false
                            items:
                              $ref: "#/components/schemas/Language"
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
  "/persons/{id}":
    get:
      tags:
      - Persons
      description: Gets a single person by their id.
      parameters:
      - name: id
        in: path
        required: true
        description: The id of the person.
        schema:
          $ref: "#/components/schemas/ResourceId"
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Person"
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No person with the specified id exists
        '500':
          description: Internal server error
  "/persons/random":
    get:
      tags:
      - Persons
      description: Gets a random single person.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Person"
        '500':
          description: Internal server error
  "/persons":
    get:
      tags:
      - Persons
      description: |
        Gets all persons.
        Full-text search is not (yet) supported.
        The results are paged.
      parameters:
      - name: sortOrder
        in: query
        required: false
        description: The order in which the persons are returned.
        schema:
          type: string
          enum:
          - NameAlphabetic
          - NameReverseAlphabetic
          #- NumberOfEditionsHighToLow
          #- NumberOfEditionsLowToHigh
          maxLength: 128
          default: NameAlphabetic
      - $ref: "#/components/parameters/PageSize"
      - $ref: "#/components/parameters/ContinuationToken"
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                description: A page of persons.
                allOf:
                  - $ref: "#/components/schemas/HalPageLinks"
                  - type: object
                    nullable: false
                    properties:
                      _embedded:
                        type: object
                        nullable: false
                        properties:
                          persons:
                            type: array
                            nullable: false
                            items:
                              $ref: "#/components/schemas/Person"
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
  "/places/{id}":
    get:
      tags:
      - Places
      description: Gets a single place by its id.
      parameters:
      - name: id
        in: path
        required: true
        description: The id of the place.
        schema:
          $ref: "#/components/schemas/ResourceId"
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Place"
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No place with the specified id exists
        '500':
          description: Internal server error
  "/places/random":
    get:
      tags:
      - Places
      description: Gets a random single place.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Place"
        '500':
          description: Internal server error
  "/places":
    get:
      tags:
      - Places
      description: |
        Gets all places.
        Full-text search is not (yet) supported.
        The results are paged.
      parameters:
      - name: sortOrder
        in: query
        required: false
        description: |
          The order in which the places are returned.
        schema:
          type: string
          enum:
          - NameAlphabetic
          - NameReverseAlphabetic
          #- NumberOfEditionsHighToLow
          #- NumberOfEditionsLowToHigh
          maxLength: 128
          default: NameAlphabetic
      - $ref: "#/components/parameters/PageSize"
      - $ref: "#/components/parameters/ContinuationToken"
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                description: A page of places.
                allOf:
                  - $ref: "#/components/schemas/HalPageLinks"
                  - type: object
                    nullable: false
                    properties:
                      _embedded:
                        type: object
                        nullable: false
                        properties:
                          places:
                            type: array
                            nullable: false
                            items:
                              $ref: "#/components/schemas/Place"
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
  "/publishers/{id}":
    get:
      tags:
      - Publishers
      description: Gets a single publisher by their id.
      parameters:
      - name: id
        in: path
        required: true
        description: The id of the genre.
        schema:
          $ref: "#/components/schemas/ResourceId"
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Publisher"
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No publisher with the specified id exists
        '500':
          description: Internal server error
  "/publishers/random":
    get:
      tags:
      - Publishers
      description: Gets a random single publisher.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Publisher"
        '500':
          description: Internal server error
  "/publishers":
    get:
      tags:
      - Publishers
      description: |
        Gets all publishers.
        Full-text search is not (yet) supported.
        The results are paged.
      parameters:
      - name: sortOrder
        in: query
        required: false
        description: The order in which the publishers are returned.
        schema:
          type: string
          enum:
          - NameAlphabetic
          - NameReverseAlphabetic
          #- NumberOfEditionsHighToLow
          #- NumberOfEditionsLowToHigh
          maxLength: 128
          default: NameAlphabetic
      - $ref: "#/components/parameters/PageSize"
      - $ref: "#/components/parameters/ContinuationToken"
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                description: A page of publishers.
                allOf:
                  - $ref: "#/components/schemas/HalPageLinks"
                  - type: object
                    nullable: false
                    properties:
                      _embedded:
                        type: object
                        nullable: false
                        properties:
                          publishers:
                            type: array
                            nullable: false
                            items:
                              $ref: "#/components/schemas/Publisher"
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
  "/subjects/{id}":
    get:
      tags:
      - Subjects
      description: Gets a single subject by its id.
      parameters:
      - name: id
        in: path
        required: true
        description: The id of the subject.
        schema:
          $ref: "#/components/schemas/ResourceId"
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Subject"
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No subject with the specified id exists
        '500':
          description: Internal server error
  "/subjects/random":
    get:
      tags:
      - Subjects
      description: Gets a random single subject.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Subject"
        '500':
          description: Internal server error
  "/subjects":
    get:
      tags:
      - Subjects
      description: |
        Gets all subjects.
        Full-text search is not (yet) supported.
        The results are paged.
      parameters:
      - name: sortOrder
        in: query
        required: false
        description: The order in which the subjects are returned.
        schema:
          type: string
          enum:
          - NameAlphabetic
          - NameReverseAlphabetic
          #- NumberOfEditionsHighToLow
          #- NumberOfEditionsLowToHigh
          maxLength: 128
          default: NameAlphabetic
      - $ref: "#/components/parameters/PageSize"
      - $ref: "#/components/parameters/ContinuationToken"
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                description: A page of subjects.
                allOf:
                  - $ref: "#/components/schemas/HalPageLinks"
                  - type: object
                    nullable: false
                    properties:
                      _embedded:
                        type: object
                        nullable: false
                        properties:
                          subjects:
                            type: array
                            nullable: false
                            items:
                              $ref: "#/components/schemas/Subject"
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
  "/times/{id}":
    get:
      tags:
      - Times
      description: Gets a single time by its id.
      parameters:
      - name: id
        in: path
        required: true
        description: The id of the time.
        schema:
          $ref: "#/components/schemas/ResourceId"
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Time"
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No time with the specified id exists
        '500':
          description: Internal server error
  "/times/random":
    get:
      tags:
      - Times
      description: Gets a random single time.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Time"
        '500':
          description: Internal server error
  "/times":
    get:
      tags:
      - Times
      description: |
        Gets all times.
        Full-text search is not (yet) supported.
        The results are paged.
      parameters:
      - name: sortOrder
        in: query
        required: false
        description: The order in which the times are returned.
        schema:
          type: string
          enum:
          - NameAlphabetic
          - NameReverseAlphabetic
          #- NumberOfEditionsHighToLow
          #- NumberOfEditionsLowToHigh
          maxLength: 128
          default: NameAlphabetic
      - $ref: "#/components/parameters/PageSize"
      - $ref: "#/components/parameters/ContinuationToken"
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                description: A page of times.
                allOf:
                  - $ref: "#/components/schemas/HalPageLinks"
                  - type: object
                    nullable: false
                    properties:
                      _embedded:
                        type: object
                        nullable: false
                        properties:
                          times:
                            type: array
                            nullable: false
                            items:
                              $ref: "#/components/schemas/Time"
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error

components:
  schemas:
    # Entity types
    Author:
      type: object
      description: A book author. E.g. Elizabeth Hamilton (1758-1816).
      allOf:
        - $ref: "#/components/schemas/HalResourceLinks"
        - $ref: "#/components/schemas/ResourceId"
        - type: object
          properties:
            name:
              type: string
              nullable: false
              description: The full name of the author.
              example: Elizabeth Hamilton
              maxLength: 2048
            about:
              type: string
              nullable: true
              description: A short description or biography of the author.
              example:
                - British botanist
                - Joanne "Jo" Murray, OBE (née Rowling), better known under the pen name J. K. Rowling, is a British author best known as the creator of the Harry Potter fantasy series, the idea for which was conceived whilst on a train trip from Manchester to London in 1990.
                  The Potter books have gained worldwide attention, won multiple awards, sold more than 400 million copies, and been the basis for a popular series of films.
              maxLength: 4000
            alternateNames:
              type: array
              nullable: false
              description: Alternative names that the author used, e.g. pseudonyms.
              example: ["Robert Galbraith"]
              maxLength: 2048
              items:
                type: string
                nullable: false
            links:
              type: array
              nullable: false
              description: Links to external resources related to the author.
              items:
                $ref: "#/components/schemas/Link"
        - type: object
          properties:
            _embedded:
              type: object
              nullable: false
              description: |
                Resources connected to the author.
                WARNING: This property is only present if the IncludeRelationships parameter on the called endpoint is set to "All".
              properties:
                books:
                  type: array
                  nullable: false
                  description: |
                    References to the books where the author is an author.
                    WARNING: This property is only present if the IncludeRelationships parameter on the called endpoint is set to "All".
                  items:
                    allOf:
                    - $ref: "#/components/schemas/HalResourceLinks"
                    - $ref: "#/components/schemas/ResourceId"
                    - $ref: "#/components/schemas/ResourceTitle"
                editions:
                  type: array
                  nullable: false
                  description: |
                    References to the editions where the author is an author.
                    WARNING: This property is only present if the IncludeRelationships parameter on the called endpoint is set to "All".
                  items:
                    allOf:
                    - $ref: "#/components/schemas/HalResourceLinks"
                    - $ref: "#/components/schemas/ResourceId"
                images:
                  type: array
                  nullable: false
                  description: |
                    References to the images of the author.
                    WARNING: This property is only present if the IncludeRelationships parameter on the called endpoint is set to "All".
                  items:
                    allOf:
                    - $ref: "#/components/schemas/HalResourceContentLinks"
                    - $ref: "#/components/schemas/ResourceId"
      additionalProperties: false
    Book:
      type: object
      description: |
        A book (work). E.g. Harry Potter and the Sorcerer's Stone by J.K. Rowling.
        See "Edition" for specific editions of a book (e.g. paperback print).
      allOf:
        - $ref: "#/components/schemas/HalResourceLinks"
        - $ref: "#/components/schemas/ResourceId"
        - type: object
          properties:
            title:
              type: string
              nullable: false
              description: The title of the book.
              example: Die Wirklichkeit des Homo sapiens
              maxLength: 2048
            subtitle:
              type: string
              nullable: true
              description: The subtitle of the book.
              example: Naturwissenschaft und menschliches Bewusstsein
              maxLength: 2048
            description: 
              type: string
              nullable: true
              description: A description of the book and/or it's contents.
              example: Explains how the animal and human inhabitants of the Sonoran Desert of Arizona, including a mountain lion, a roadrunner, a coyote, a tortoise, and members of the Papago Indian tribe, adapt to and survive the desert's merciless heat.
              maxLength: 4000
            links:
              type: array
              nullable: false
              description: Links to external resources related to the book.
              items:
                $ref: "#/components/schemas/Link"
        - type: object
          properties:
            _embedded:
              type: object
              nullable: false
              description: |
                Resources connected to the book.
                WARNING: This property is only present if the IncludeRelationships parameter on the called endpoint is set to "All".
              properties:
                authors:
                  type: array
                  nullable: false
                  description: |
                    References to the authors of the book.
                    WARNING: This property is only present if the IncludeRelationships parameter on the called endpoint is set to "All".
                  items:
                      allOf:
                      - $ref: "#/components/schemas/HalResourceLinks"
                      - $ref: "#/components/schemas/ResourceId"
                      - $ref: "#/components/schemas/ResourceName"
                subjects:
                  type: array
                  nullable: false
                  description: |
                    References to the subjects handled in the books content.
                    WARNING: This property is only present if the IncludeRelationships parameter on the called endpoint is set to "All".
                  items:
                    allOf:
                    - $ref: "#/components/schemas/HalResourceLinks"
                    - $ref: "#/components/schemas/ResourceId"
                    - $ref: "#/components/schemas/ResourceName"
                places:
                  type: array
                  nullable: false
                  description: |
                    References to the places handled in the books contents.
                    WARNING: This property is only present if the IncludeRelationships parameter on the called endpoint is set to "All".
                  items:
                    allOf:
                    - $ref: "#/components/schemas/HalResourceLinks"
                    - $ref: "#/components/schemas/ResourceId"
                    - $ref: "#/components/schemas/ResourceName"
                times:
                  type: array
                  nullable: false
                  description: |
                    References to the times handled in the books contents.
                    WARNING: This property is only present if the IncludeRelationships parameter on the called endpoint is set to "All".
                  items:
                    allOf:
                    - $ref: "#/components/schemas/HalResourceLinks"
                    - $ref: "#/components/schemas/ResourceId"
                    - $ref: "#/components/schemas/ResourceName"
                persons:
                  type: array
                  nullable: false
                  description: |
                    References to the persons handled in the books contents.
                    WARNING: This property is only present if the IncludeRelationships parameter on the called endpoint is set to "All".
                  items:
                    allOf:
                    - $ref: "#/components/schemas/HalResourceLinks"
                    - $ref: "#/components/schemas/ResourceId"
                    - $ref: "#/components/schemas/ResourceName"
                editions:
                  type: array
                  nullable: false
                  description: |
                    References to the editions of this book.
                    WARNING: This property is only present if the IncludeRelationships parameter on the called endpoint is set to "All".
                  items:
                    allOf:
                    - $ref: "#/components/schemas/HalResourceLinks"
                    - $ref: "#/components/schemas/ResourceId"
                images:
                  type: array
                  nullable: false
                  description: |
                    References to the images of the book.
                    WARNING: This property is only present if the IncludeRelationships parameter on the called endpoint is set to "All".
                  items:
                      allOf:
                      - $ref: "#/components/schemas/HalResourceContentLinks"
                      - $ref: "#/components/schemas/ResourceId"
      additionalProperties: false
    Edition:
      type: object
      description: |
        A specific edition of a book. E.g. the first/second version or a paperback print of a book.
        See "Book" for a book work (e.g. Harry Potter and the Sorcerer's Stone by J.K. Rowling).
      allOf:
        - $ref: "#/components/schemas/HalResourceLinks"
        - $ref: "#/components/schemas/ResourceId"
        - type: object
          properties:
            title:
              type: string
              nullable: true
              description: The title of the editon.
              example: Die Wirklichkeit des Homo sapiens
              maxLength: 2048
            subtitle:
              type: string
              nullable: true
              description: The subtitle of the edition.
              example: Naturwissenschaft und menschliches Bewusstsein
              maxLength: 2048
            editionName:
              type: string
              nullable: true
              description: The name of the edition.
              example: 2nd ed.
              maxLength: 2048
            description: 
              type: string
              nullable: true
              description: A description of the edition and/or it's contents.
              example: Explains how the animal and human inhabitants of the Sonoran Desert of Arizona, including a mountain lion, a roadrunner, a coyote, a tortoise, and members of the Papago Indian tribe, adapt to and survive the desert's merciless heat.
              maxLength: 4000
            pageCount:
              type: number
              format: integer  
              nullable: true
              description: The number of pages of the edition.
              example: 125
              minimum: 1
              maximum: 10000
            alternateTitles:
              type: array
              nullable: false
              description: Alternative titles of the edition.
              example: A translation of the edition title.
              items:
                type: string
                nullable: false
                maxLength: 2048
            bindings:
              type: array
              nullable: false
              description: The binding types of the edition.
              example: Paperback
              items:
                type: string
                enum:
                  - Unknown
                  - Paperback
                  - PerfectPaperback
                  - Hardcover
                  - Softcover
                  - Comic
                  - Unbound
                  - RingBound
                  - Brochure
                  - Stapled
                  - Textbook
                  - LooseLeaf
                  - MassMarketPaperback
                  - SpiralBound
                  - Magazine
                  - BoardBook
                  - RagBook
                  - Turtleback
                  - Cardbook
                  - PlasticComb
                  - Pamphlet
                  - Flexibound
                  - Transparency
                  - PopUp
                  - Leaflet
                  - FlashCards
                  - SlideBook
                  - Audiobook
                  - ElectronicBook
                nullable: false
                maxLength: 128
            isbns:
              type: array
              nullable: false
              description: |
                The ISBNs (ISBN-10 and ISBN-13) of the edition.
                Guaranteed to be valid ISBNs.
              example:
                - "9780825620492"
                - "082562049X"
              items:
                type: string
                nullable: false
                maxLength: 13
            contributions:
              type: array
              nullable: false
              description: Entities that have contributed to the edition.
              example: Hong Kong Polytechnic University
              items:
                type: string
                nullable: false
                maxLength: 2048
            uris:
              type: array
              nullable: false
              description: |
                URIs to external resources related to the edition.
                Not guaranteed to contain a protocol (e.g. https://).
              items:
                type: string
                format: uri
                nullable: false
                maxLength: 2048
            libraryOfCongressClassifications:
              type: array
              nullable: false
              description: |
                The Library of Congress Classifications (LCCs) of the edition.
                Not guaranteed to be valid LCCs.
              example: PZ7.J684 Wj 1982
              items:
                type: string
                nullable: false
                maxLength: 64
            libraryOfCongressControlNumbers:
              type: array
              nullable: false
              description: |
                The Library of Congress Control Numbers (LCCNs) of the edition. 
                Not guaranteed to be valid LCCNs.
              example: "42037605"
              items:
                type: string
                nullable: false
                maxLength: 64
            deweyDecimalClasses:
              type: array
              nullable: false
              description: |
                The Dewey Decimal Classes (DDCs) of the edition.
                Not guaranteed to be valid DDCs.
              example:
                - "516"
                - "006.752"
              items:
                type: string
                nullable: false
                maxLength: 256
            onlineComputerLibraryCenterNumbers:
              type: array
              nullable: false
              description: |
                The Online Computer Library Center (OCLC) numbers of the edition.
                Not guaranteed to be valid OCLC numbers.
              example: "16585060"
              items:
                type: string
                nullable: false
                maxLength: 64
        - type: object
          properties:
            _embedded:
              type: object
              nullable: false
              description: |
                Resources connected to the edition.
                WARNING: This property is only present if the IncludeRelationships parameter on the called endpoint is set to "All".
              properties:
                translatedFromLanguage:
                  type: object
                  nullable: true
                  description: |
                    Reference to the language that this editions has been translated from.
                    WARNING: This property is only present if the edition has been translated from a language (has a value other than null).
                  allOf:
                  - $ref: "#/components/schemas/HalResourceLinks"
                  - $ref: "#/components/schemas/ResourceId"
                authors:
                  type: array
                  nullable: false
                  description: |
                    References to the authors of the edition.
                    WARNING: This property is only present if the IncludeRelationships parameter on the called endpoint is set to "All".
                  items:
                    allOf:
                    - $ref: "#/components/schemas/HalResourceLinks"
                    - $ref: "#/components/schemas/ResourceId"
                    - $ref: "#/components/schemas/ResourceName"
                languages:
                  type: array
                  nullable: false
                  description: |
                    References to the languages that the edition exists in.
                    In most cases, an edition exists in a single language.
                    WARNING: This property is only present if the IncludeRelationships parameter on the called endpoint is set to "All".
                  items:
                    allOf:
                    - $ref: "#/components/schemas/HalResourceLinks"
                    - $ref: "#/components/schemas/ResourceId"
                publishers:
                  type: array
                  nullable: false
                  description: |
                    References to the publishers of the edition.
                    WARNING: This property is only present if the IncludeRelationships parameter on the called endpoint is set to "All".
                  items:
                    allOf:
                    - $ref: "#/components/schemas/HalResourceLinks"
                    - $ref: "#/components/schemas/ResourceId"
                    - $ref: "#/components/schemas/ResourceName"
                publishPlaces:
                  type: array
                  nullable: false
                  description: |
                    References to the places that the edition has been published at.
                    WARNING: This property is only present if the IncludeRelationships parameter on the called endpoint is set to "All".
                  items:
                    allOf:
                    - $ref: "#/components/schemas/HalResourceLinks"
                    - $ref: "#/components/schemas/ResourceId"
                    - $ref: "#/components/schemas/ResourceName"
                genres:
                  type: array
                  nullable: false
                  description: |
                    References to the genres that the edition belongs to.
                    WARNING: This property is only present if the IncludeRelationships parameter on the called endpoint is set to "All".
                  items:
                    allOf:
                    - $ref: "#/components/schemas/HalResourceLinks"
                    - $ref: "#/components/schemas/ResourceId"
                    - $ref: "#/components/schemas/ResourceName"
                books:
                  type: array
                  nullable: false
                  description: |
                    References to the books (works) that this edition belongs to.
                    In most cases, an edition belongs to a single book.
                    WARNING: This property is only present if the IncludeRelationships parameter on the called endpoint is set to "All".
                  items:
                    allOf:
                    - $ref: "#/components/schemas/HalResourceLinks"
                    - $ref: "#/components/schemas/ResourceId"
                images:
                  type: array
                  nullable: false
                  description: |
                    References to the images of the edition.
                    WARNING: This property is only present if the IncludeRelationships parameter on the called endpoint is set to "All".
                  items:
                    allOf:
                    - $ref: "#/components/schemas/HalResourceContentLinks"
                    - $ref: "#/components/schemas/ResourceId"
      additionalProperties: false
    Genre:
      type: object
      description: A stylistic category of literature.
      allOf:
        - $ref: "#/components/schemas/ResourceId"
        - type: object
          properties:
            name:
              type: string
              nullable: true
              description: The name of the genre.
              example: Fiction
              maxLength: 2048
      additionalProperties: false
    Language:
      type: object
      description: An ISO 639-3 language.
      allOf:
        - $ref: "#/components/schemas/ResourceId"
        - type: object 
          properties:
            iso639Code:
              type: string
              nullable: false
              description: |
                The ISO 639-3 code of the language.
                Guaranteed to be stable.
              example: eng
              minLength: 3
              maxLength: 3
            englishName:
              type: string
              nullable: false
              description: |
                An english name for the language.
                Not guaranteed to be stable.
              example: English
              maxLength: 256
          additionalProperties: false
    Link:
      type: object
      description: A link to an external resource.
      properties:
        title:
          type: string
          nullable: false
          description: The title of the link.
          example: Wikidata
          maxLength: 2048
        uri:
          type: string
          format: uri
          nullable: false
          description: |
           The URI of the link.
           Not guaranteed to contain a protocol (e.g. https://).
          example: https://www.wikidata.org/wiki/Q97155744
          maxLength: 2048
      additionalProperties: false
    Person:
      type: object
      description: A natural or fictional person.
      allOf:
        - $ref: "#/components/schemas/ResourceId"
        - type: object
          properties:
            name:
              type: string
              nullable: true
              description: The name of the person.
              example: José Martiniano de Alencar (1829-1877)
              maxLength: 2048
      additionalProperties: false
    Place:
      type: object
      description: A real or fictional location.
      allOf:
        - $ref: "#/components/schemas/ResourceId"
        - type: object
          properties:
            name:
              type: string
              nullable: true
              description: The name of the place.
              example:
                - Brazil
                - Middle East
                - Tennessee
                - Hogwarts
              maxLength: 2048
      additionalProperties: false
    Publisher:
      type: object
      description: A book publisher.
      allOf:
        - $ref: "#/components/schemas/ResourceId"
        - type: object
          properties:
            name:
              type: string
              nullable: true
              description: The name of the book publisher.
              example: Addison Wesley Pub Ltd
              maxLength: 2048
      additionalProperties: false
    Subject:
      type: object
      description: A subject handled by a books contents.
      allOf:
        - $ref: "#/components/schemas/ResourceId"
        - type: object
          properties:
            name:
              type: string
              nullable: true
              description: The name of the subject.
              example:
                - Poverty
                - Navigation
                - Sex
              maxLength: 2048
      additionalProperties: false
    Time:
      type: object
      description: A period or moment in time.
      allOf:
        - $ref: "#/components/schemas/ResourceId"
        - type: object
          properties:
            name:
              type: string
              nullable: true
              description: The name of the time.
              example:
                - Qājār dynasty, 1794-1925
                - Pre-modern
                - "2011"
                - 1876-1939
                - To 1339
              maxLength: 2048
      additionalProperties: false
    
    # Auxilliary types
    Error:
      type: object
      properties:
        errorCode:
          type: string
          enum:
            - MISSING_API_KEY
            - INVALID_API_KEY
            - NO_API_CALLS_REMAINING
            - INVALID_FORMAT_ID
            - INVALID_FORMAT_CONTINUATION_TOKEN
            - MISSING_SEARCH_PARAMETERS
            - INVALID_VALUE
          nullable: false
          description: A stable identifier of the error.
          maxLength: 256
        errorMessage:
          type: string
          nullable: false
          description: A human readable description of the error.
          maxLength: 4000
        problematicParameter:
          type: string
          nullable: true
          default: The parameter(s) that is/are causing the error.
          maxLength: 256
      additionalProperties: false
    
    # HAL types
    HalResourceLinks:
      type: object
      nullable: false
      description: Hypertext Application Language (HAL) links for the resource.
      properties:
        _link:
          type: object
          nullable: false
          properties:
            self:
              type: object
              nullable: false
              description: The link to the resource.
              properties:
                href:
                  type: string
                  format: uri
                  nullable: false
                  description: The URL of the resource.
                  example: https://api.bookdatabase.io/v1/authors/10e1cd03-9099-ec11-8487-704d7b630b44
                  maxLength: 2048
                type:
                  $ref: "#/components/schemas/HalResourceTypes"
      additionalProperties: false
    HalResourceContentLinks:
      type: object
      nullable: false
      description: Hypertext Application Language (HAL) links for the resource with content.
      properties:
        _link:
          type: object
          nullable: false
          properties:
            contentUrl:
              type: object
              nullable: false
              description: The link to the resource content URL.
              properties:
                href:
                  type: string
                  format: uri
                  nullable: false
                  description: The URL of the resource.
                  example: https://api.bookdatabase.io/v1/images/10e1cd03-9099-ec11-8487-704d7b630b44/contentUrl"
                  maxLength: 2048
      additionalProperties: false
    HalPageLinks:
      type: object
      nullable: false
      description: The Hypertext Application Language (HAL) links for the page.
      properties:
        _link:
          type: object
          nullable: false
          properties:
            self:
              type: object
              nullable: false
              description: |
                The link to the page.
                If present, the value and format of the continuationToken parameter in the URL are not guaranteed to be stable.
              properties:
                href:
                  type: string
                  format: uri
                  nullable: false
                  description: The URI of the page.
                  example: https://api.bookdatabase.io/v1/authors?bookId=78a63bba-c09c-ec11-8487-704d7b630b44&pageSize=1
                  maxLength: 2048
                type:
                  $ref: "#/components/schemas/HalPageTypes"
            first:
              type: object
              nullable: false
              description: The link to the first page of the result set.
              properties:
                href:
                  type: string
                  format: uri
                  nullable: false
                  description: The URI of the page.
                  example: https://api.bookdatabase.io/v1/authors?bookId=78a63bba-c09c-ec11-8487-704d7b630b44&pageSize=1
                  maxLength: 2048
                type:
                  $ref: "#/components/schemas/HalPageTypes"
            next:
              type: object
              nullable: true
              description: |
                The link to the next page of the result set.
                The value and format of the continuationToken parameter in the URL are not guaranteed to be stable.
                WARNING: This property is only present if there is a next page.
              properties:
                href:
                  type: string
                  format: uri
                  nullable: false
                  description: The URI of the page.
                  example: https://api.bookdatabase.io/v1/authors?bookId=78a63bba-c09c-ec11-8487-704d7b630b44&pageSize=1&continuationToken=10e1cd03-9099-ec11-8487-704d7b630b44
                  maxLength: 2048
                type:
                  $ref: "#/components/schemas/HalPageTypes"
      additionalProperties: false
    HalResourceTypes:
      type: string
      enum:
        - author
        - book
        - edition
        - publisher
        - genre
        - language
        - subject
        - place
        - time
        - person
      nullable: false
      description: The type of resource.
      maxLength: 128
    HalPageTypes:
      type: string
      enum:
        - page<author>
        - page<book>
        - page<edition>
        - page<publisher>
        - page<genre>
        - page<language>
        - page<subject>
        - page<place>
        - page<time>
        - page<person>
      nullable: false
      description: The type of page. 
      maxLength: 128
    
    # Reusable properties
    ResourceId:
      properties:
        id:
          type: string
          nullable: false
          description: |
            The bookdatabase.io identifier of the resource.
            Any processing or interpretation of this value is discouraged, treat it as a string.
            The value and format are not guaranteed to be stable.
          example: 10e1cd03-9099-ec11-8487-704d7b630b44
          maxLength: 128
    ResourceName:
      properties:
        name:
          type: string
          nullable: false
          description: The name of the resource.
          maxLength: 2048
    ResourceTitle:
      properties:
        name:
          type: string
          nullable: false
          description: The title of the resource.
          maxLength: 2048
  
  parameters:
    SearchQuery:
      name: searchQuery
      in: query
      required: false
      description: |
        The value to search the searchable resource properties with (full-text search).
        Characters other than letters and numbers are ignored.
        If the searchQuery contains multiple words (characters separated by whitespace), all words are searched for separately.
        All words must match a resource for the resource to match.
        Specifying a searchQuery limits the maximum amount of results to 100.
      schema:
        type: string
        maxLength: 128
    SearchMode:
      name: searchMode
      in: query
      required: false
      description: |
        The mode to use for comparing the specified searchQuery against the searchable resource properties.
        Exact: Values have to match exactly. searchQuery "lizabeth" does not match "Elizabeth Hamilton".
        Fuzzy: Values have to match approximately. searchQueries "lizabeth Hamilton" matches "Elizabeth Hamilton".
        If not specified, Exact is used.
        If no searchQuery is specified, this parameter has no effect.
      schema:
        type: string
        enum:
        - Exact
        - Fuzzy
        maxLength: 128
        example: Exact
    PageSize:
      name: pageSize
      in: query
      required: false
      description: The maximum amount of resources per result page (1-100).
      schema:
        type: number
        format: integer
        default: 10
        minimum: 1
        maximum: 100
    ContinuationToken:
      name: continuationToken
      in: query
      required: false
      description: |
        The token to access a specific page of a paged endpoint.
        In most cases, this should not be used directly.
        Instead, access the URL provided in _links.next.href of the previous page.
      schema:
        type: string
        maxLength: 128
    IncludeRelationships:
      name: includeRelationships
      in: query
      required: false
      description: |
        The relationships to other resources which to include in the results.
        Including less data reduces the response size and can reduce response times.
      schema:
        type: string
        enum:
        - All
        - None
        maxLength: 128
        default: All
        example: All

  securitySchemes:
    ApiKey:
      type: apiKey
      description: Your current API Key
      name: X-API-Key
      in: header

security:
- ApiKey:
  - ApiKey
