openapi: 3.0.3
info:
  title: Quote Garden Authors API
  version: 3.0.0
  description: "Quote Garden is a free, open-source REST API serving a curated database of 75,000+\nfamous quotes. The v3 API is read-only, requires no authentication, and exposes four\nresource endpoints: random quotes, paginated quote listings, the master genre list,\nand the master author list.\n\nAll responses share the same envelope:\n\n```json\n{\n  \"statusCode\": 200,\n  \"message\": \"Quotes\",\n  \"pagination\": { \"currentPage\": 1, \"nextPage\": 2, \"totalPages\": 4 },\n  \"totalQuotes\": 4,\n  \"data\": [ /* resource objects or strings */ ]\n}\n```\n\nThe canonical reference deployment is hosted on Render. The project is MIT-licensed\nand self-hostable from the GitHub source (Node.js + Express + MongoDB).\n"
  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
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: Authors
  description: Master list of authors represented in the quote corpus.
paths:
  /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:
  examples:
    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
  schemas:
    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: {}
    Error:
      type: object
      properties:
        statusCode:
          type: integer
          example: 500
        message:
          type: string
          example: Internal Server Error
    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
    StringListResponse:
      allOf:
      - $ref: '#/components/schemas/ResponseEnvelope'
      - type: object
        properties:
          data:
            type: array
            items:
              type: string
  responses:
    ServerError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    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
    Page:
      name: page
      in: query
      description: One-indexed page number for paginated responses.
      required: false
      schema:
        type: integer
        minimum: 1
        default: 1
externalDocs:
  description: GitHub README and API documentation
  url: https://github.com/pprathameshmore/QuoteGarden#api-documentation