openapi: 3.0.3
info:
  title: Quote Garden API
  version: '3.0.0'
  description: |
    Quote Garden is a free, open-source REST API serving a curated database of 75,000+
    famous quotes. The v3 API is read-only, requires no authentication, and exposes four
    resource endpoints: random quotes, paginated quote listings, the master genre list,
    and the master author list.

    All responses share the same envelope:

    ```json
    {
      "statusCode": 200,
      "message": "Quotes",
      "pagination": { "currentPage": 1, "nextPage": 2, "totalPages": 4 },
      "totalQuotes": 4,
      "data": [ /* resource objects or strings */ ]
    }
    ```

    The canonical reference deployment is hosted on Render. The project is MIT-licensed
    and self-hostable from the GitHub source (Node.js + Express + MongoDB).
  contact:
    name: Prathamesh More
    url: https://github.com/pprathameshmore/QuoteGarden
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  termsOfService: https://github.com/pprathameshmore/QuoteGarden#readme
externalDocs:
  description: GitHub README and API documentation
  url: https://github.com/pprathameshmore/QuoteGarden#api-documentation
servers:
  - url: https://quote-garden.onrender.com/api/v3
    description: Public reference deployment (Render)
  - url: https://quote-garden.herokuapp.com/api/v3
    description: Legacy reference deployment (Heroku, deprecated)
tags:
  - name: Quotes
    description: Operations for retrieving quote records, individually at random or as a paginated list.
  - name: Authors
    description: Master list of authors represented in the quote corpus.
  - name: Genres
    description: Master list of genres / categories represented in the quote corpus.
paths:
  /quotes/random:
    get:
      summary: Get Random Quote
      description: |
        Returns one or more randomly selected quotes, optionally filtered by author, genre,
        and/or a full-text search query. When `count` is supplied, that many random quotes
        are returned (default 1).
      operationId: getRandomQuote
      tags:
        - Quotes
      parameters:
        - $ref: '#/components/parameters/AuthorFilter'
        - $ref: '#/components/parameters/GenreFilter'
        - $ref: '#/components/parameters/QueryFilter'
        - name: count
          in: query
          description: Number of random quotes to return.
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 1
      responses:
        '200':
          description: One or more random quotes wrapped in the standard envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuotesResponse'
              examples:
                random:
                  $ref: '#/components/examples/RandomQuoteResponse'
        '500':
          $ref: '#/components/responses/ServerError'
  /quotes:
    get:
      summary: List Quotes
      description: |
        Returns a paginated list of quotes, optionally filtered by author, genre, and/or a
        full-text search query. Supports standard `page` and `limit` query parameters.
      operationId: listQuotes
      tags:
        - Quotes
      parameters:
        - $ref: '#/components/parameters/AuthorFilter'
        - $ref: '#/components/parameters/GenreFilter'
        - $ref: '#/components/parameters/QueryFilter'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A paginated list of quotes wrapped in the standard envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuotesResponse'
              examples:
                page:
                  $ref: '#/components/examples/ListQuotesResponse'
        '500':
          $ref: '#/components/responses/ServerError'
  /genres:
    get:
      summary: List Genres
      description: Returns the master list of all genres present in the corpus.
      operationId: listGenres
      tags:
        - Genres
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A list of genre name strings wrapped in the standard envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StringListResponse'
              examples:
                genres:
                  $ref: '#/components/examples/GenresResponse'
        '500':
          $ref: '#/components/responses/ServerError'
  /authors:
    get:
      summary: List Authors
      description: Returns the master list of all authors present in the corpus.
      operationId: listAuthors
      tags:
        - Authors
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A list of author name strings wrapped in the standard envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StringListResponse'
              examples:
                authors:
                  $ref: '#/components/examples/AuthorsResponse'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  parameters:
    AuthorFilter:
      name: author
      in: query
      description: Filter results to quotes by this exact author name.
      required: false
      schema:
        type: string
    GenreFilter:
      name: genre
      in: query
      description: Filter results to quotes tagged with this genre.
      required: false
      schema:
        type: string
    QueryFilter:
      name: query
      in: query
      description: Full-text search across quoteText, quoteAuthor, and quoteGenre.
      required: false
      schema:
        type: string
    Page:
      name: page
      in: query
      description: One-indexed page number for paginated responses.
      required: false
      schema:
        type: integer
        minimum: 1
        default: 1
    Limit:
      name: limit
      in: query
      description: Maximum number of records to return per page.
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 10
  schemas:
    Quote:
      type: object
      description: A single quote record stored in the Quote Garden MongoDB collection.
      required:
        - _id
        - quoteText
        - quoteAuthor
        - quoteGenre
      properties:
        _id:
          type: string
          description: MongoDB ObjectId of the quote.
          example: 5eb17ab3b69dc744b4e81942
        quoteText:
          type: string
          description: The verbatim quote text.
          example: I think the thing we see is that as people are using video games more, they tend to watch passive TV a bit less.
        quoteAuthor:
          type: string
          description: Name of the person to whom the quote is attributed.
          example: Bill Gates
        quoteGenre:
          type: string
          description: Single genre tag classifying the quote.
          example: time
        __v:
          type: integer
          description: Mongoose document version key.
          example: 0
    Pagination:
      type: object
      description: Pagination block returned on every response.
      properties:
        currentPage:
          type: integer
          nullable: true
          example: 1
        nextPage:
          type: integer
          nullable: true
          example: 2
        totalPages:
          type: integer
          nullable: true
          example: 4
    ResponseEnvelope:
      type: object
      description: Common response envelope shared by all endpoints.
      required:
        - statusCode
        - message
        - pagination
        - data
      properties:
        statusCode:
          type: integer
          example: 200
        message:
          type: string
          example: Quotes
        pagination:
          $ref: '#/components/schemas/Pagination'
        totalQuotes:
          type: integer
          nullable: true
          example: 4
        data:
          type: array
          items: {}
    QuotesResponse:
      allOf:
        - $ref: '#/components/schemas/ResponseEnvelope'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/Quote'
    StringListResponse:
      allOf:
        - $ref: '#/components/schemas/ResponseEnvelope'
        - type: object
          properties:
            data:
              type: array
              items:
                type: string
    Error:
      type: object
      properties:
        statusCode:
          type: integer
          example: 500
        message:
          type: string
          example: Internal Server Error
  responses:
    ServerError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  examples:
    RandomQuoteResponse:
      summary: Single random quote
      value:
        statusCode: 200
        message: Random quotes
        pagination:
          currentPage: 1
          nextPage: null
          totalPages: 1
        totalQuotes: 1
        data:
          - _id: 5eb17ab3b69dc744b4e81942
            quoteText: I think the thing we see is that as people are using video games more, they tend to watch passive TV a bit less.
            quoteAuthor: Bill Gates
            quoteGenre: time
            __v: 0
    ListQuotesResponse:
      summary: Paginated quote list
      value:
        statusCode: 200
        message: Quotes
        pagination:
          currentPage: 1
          nextPage: 2
          totalPages: 4
        totalQuotes: 4
        data:
          - _id: 5eb17aaeb69dc744b4e72a4a
            quoteText: The first rule of any technology used in a business is that automation applied to an efficient operation will magnify the efficiency. The second is that automation applied to an inefficient operation will magnify the inefficiency.
            quoteAuthor: Bill Gates
            quoteGenre: business
            __v: 0
    GenresResponse:
      summary: All genres
      value:
        statusCode: 200
        message: Genres
        pagination:
          currentPage: null
          nextPage: null
          totalPages: null
        totalQuotes: null
        data:
          - age
          - business
          - life
          - love
          - success
          - time
    AuthorsResponse:
      summary: All authors
      value:
        statusCode: 200
        message: Authors
        pagination:
          currentPage: null
          nextPage: null
          totalPages: null
        totalQuotes: null
        data:
          - Bill Gates
          - Albert Einstein
          - Mark Twain
          - Maya Angelou