openapi.yaml

openapi: 3.0.3
info:
  title: Bookstore API
  description: |

    A comprehensive REST API for managing an online bookstore.

servers:
  - url: https://api.bookstore.example.com/v1
    description: Production server
  - url: https://staging-api.bookstore.example.com/v1
    description: Staging server for testing

tags:
  - name: Books
    description: |
      Operations for managing the book catalog including browsing, searching, 
      and inventory management. Books can be filtered by genre, author, or other criteria.
  - name: Orders
    description: |
      Order management operations including creating new orders, tracking order status,
      and viewing order history. Requires authentication.
  - name: Users
    description: |
      User account operations including registration, authentication, and profile management.
      Some operations require authentication.

paths:
  /books:
    get:
      tags: [Books]
      summary: List all books
      description: |
        Retrieves a paginated list of books from the catalog. Supports filtering by various criteria
        and sorting options. Results include pagination metadata for easy navigation.
      operationId: listBooks
      parameters:
        - name: genre
          in: query
          description: Filter books by genre (case-insensitive)
          schema:
            type: string
            enum: [fiction, non-fiction, mystery, romance, sci-fi, fantasy, biography, history, science, technology]
            example: fiction
        - name: author
          in: query
          description: Filter books by author name (partial match supported)
          schema:
            type: string
            example: "F. Scott Fitzgerald"
        - name: title
          in: query
          description: Search books by title (partial match supported)
          schema:
            type: string
            example: "Great Gatsby"
        - name: minPrice
          in: query
          description: Minimum price filter
          schema:
            type: number
            format: float
            minimum: 0
            example: 10.00
        - name: maxPrice
          in: query
          description: Maximum price filter
          schema:
            type: number
            format: float
            minimum: 0
            example: 50.00
        - name: inStock
          in: query
          description: Filter by availability
          schema:
            type: boolean
            example: true
        - name: sortBy
          in: query
          description: Sort field
          schema:
            type: string
            enum: [title, author, price, stock, createdAt]
            default: title
        - name: sortOrder
          in: query
          description: Sort order
          schema:
            type: string
            enum: [asc, desc]
            default: asc
        - name: page
          in: query
          description: Page number (1-based)
          schema:
            type: integer
            minimum: 1
            default: 1
            example: 1
        - name: limit
          in: query
          description: Number of items per page
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
            example: 20
      responses:
        "200":
          description: Successfully retrieved books list
          headers:
            X-Total-Count:
              description: Total number of books matching the criteria
              schema:
                type: integer
            X-Page-Count:
              description: Total number of pages
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BookListResponse"
              examples:
                success:
                  summary: Successful response with books
                  value:
                    data:
                      - id: "b_123"
                        title: "The Great Gatsby"
                        author: "F. Scott Fitzgerald"
                        genre: "fiction"
                        price: 12.99
                        stock: 42
                        isbn: "978-0-7432-7356-5"
                        publishedDate: "1925-04-10"
                        description: "A classic American novel set in the Jazz Age"
                      - id: "b_124"
                        title: "To Kill a Mockingbird"
                        author: "Harper Lee"
                        genre: "fiction"
                        price: 14.99
                        stock: 28
                        isbn: "978-0-06-112008-4"
                        publishedDate: "1960-07-11"
                        description: "A gripping tale of racial injustice and childhood innocence"
                    pagination:
                      page: 1
                      limit: 20
                      total: 156
                      totalPages: 8
                      hasNext: true
                      hasPrev: false
        "400":
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalidParams:
                  summary: Invalid parameters
                  value:
                    code: "INVALID_PARAMETERS"
                    message: "Invalid sort field specified"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /books/{bookId}:
    get:
      tags: [Books]
      summary: Get a specific book
      description: |
        Retrieves detailed information about a specific book by its unique identifier.
        Returns comprehensive book details including stock information and metadata.
      operationId: getBook
      parameters:
        - name: bookId
          in: path
          required: true
          description: Unique identifier for the book
          schema:
            type: string
            pattern: '^b_[a-zA-Z0-9]+$'
            example: "b_123"
      responses:
        "200":
          description: Book details retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Book"
              examples:
                bookDetails:
                  summary: Complete book information
                  value:
                    id: "b_123"
                    title: "The Great Gatsby"
                    author: "F. Scott Fitzgerald"
                    genre: "fiction"
                    price: 12.99
                    stock: 42
                    isbn: "978-0-7432-7356-5"
                    publishedDate: "1925-04-10"
                    description: "A classic American novel set in the Jazz Age, exploring themes of wealth, love, and the American Dream."
                    publisher: "Scribner"
                    pages: 180
                    language: "English"
                    createdAt: "2024-01-15T10:30:00Z"
                    updatedAt: "2024-03-20T14:45:00Z"
        "400":
          description: Invalid book ID format
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalidId:
                  summary: Invalid book ID
                  value:
                    code: "INVALID_BOOK_ID"
                    message: "Book ID must follow the format 'b_' followed by alphanumeric characters"
        "404":
          description: Book not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                notFound:
                  summary: Book not found
                  value:
                    code: "BOOK_NOT_FOUND"
                    message: "No book found with the specified ID"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    
    post:
      tags: [Books]
      summary: Create a new book
      description: |
        Adds a new book to the catalog. Requires admin authentication.
        All book details including title, author, and pricing information must be provided.
      operationId: createBook
      security:
        - BearerAuth: []
      requestBody:
        required: true
        description: Book information to create
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateBookRequest"
            examples:
              newBook:
                summary: New book creation
                value:
                  title: "The Catcher in the Rye"
                  author: "J.D. Salinger"
                  genre: "fiction"
                  price: 13.99
                  stock: 25
                  isbn: "978-0-316-76948-0"
                  publishedDate: "1951-07-16"
                  description: "A controversial novel about teenage rebellion and alienation"
                  publisher: "Little, Brown and Company"
                  pages: 277
                  language: "English"
      responses:
        "201":
          description: Book created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Book"
        "400":
          description: Invalid book data
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized - Admin access required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: Book with this ISBN already exists
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /orders:
    get:
      tags: [Orders]
      summary: List user orders
      description: |
        Retrieves a paginated list of orders for the authenticated user.
        Orders are returned in descending order by creation date.
      operationId: listOrders
      security:
        - BearerAuth: []
      parameters:
        - name: status
          in: query
          description: Filter orders by status
          schema:
            type: string
            enum: [pending, confirmed, shipped, delivered, cancelled]
        - name: page
          in: query
          description: Page number (1-based)
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: limit
          in: query
          description: Number of orders per page
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 10
      responses:
        "200":
          description: Orders retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrderListResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    
    post:
      tags: [Orders]
      summary: Create a new order
      description: |
        Places a new order for the authenticated user. The order will be created with 'pending' status
        and can contain multiple books with specified quantities. Stock availability is checked automatically.
      operationId: createOrder
      security:
        - BearerAuth: []
      requestBody:
        required: true
        description: Order details including items and shipping information
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateOrderRequest"
            examples:
              singleBook:
                summary: Order with single book
                value:
                  items:
                    - bookId: "b_123"
                      quantity: 2
                  shippingAddress:
                    street: "123 Main St"
                    city: "New York"
                    state: "NY"
                    zipCode: "10001"
                    country: "USA"
              multipleBooks:
                summary: Order with multiple books
                value:
                  items:
                    - bookId: "b_123"
                      quantity: 1
                    - bookId: "b_124"
                      quantity: 3
                  shippingAddress:
                    street: "456 Oak Ave"
                    city: "Los Angeles"
                    state: "CA"
                    zipCode: "90210"
                    country: "USA"
      responses:
        "201":
          description: Order created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
              examples:
                newOrder:
                  summary: Newly created order
                  value:
                    id: "ord_789"
                    userId: "u_456"
                    items:
                      - bookId: "b_123"
                        quantity: 2
                        unitPrice: 12.99
                        subtotal: 25.98
                    subtotal: 25.98
                    tax: 2.08
                    shipping: 5.99
                    total: 34.05
                    status: "pending"
                    shippingAddress:
                      street: "123 Main St"
                      city: "New York"
                      state: "NY"
                      zipCode: "10001"
                      country: "USA"
                    createdAt: "2024-03-23T10:30:00Z"
                    estimatedDelivery: "2024-03-30T00:00:00Z"
        "400":
          description: Invalid order data or insufficient stock
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                insufficientStock:
                  summary: Insufficient stock
                  value:
                    code: "INSUFFICIENT_STOCK"
                    message: "Not enough stock available for book 'The Great Gatsby'. Available: 5, Requested: 10"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /orders/{orderId}:
    get:
      tags: [Orders]
      summary: Get order details
      operationId: getOrder
      security:
        - BearerAuth: []
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Order details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
        "404":
          description: Order not found

  /users/register:
    post:
      tags: [Users]
      summary: Register a new user account
      description: |
        Creates a new user account with the provided information. Email addresses must be unique.
        Password must meet security requirements (minimum 8 characters, at least one uppercase,
        one lowercase, one number, and one special character).
      operationId: registerUser
      requestBody:
        required: true
        description: User registration information
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RegisterRequest"
            examples:
              newUser:
                summary: New user registration
                value:
                  name: "John Doe"
                  email: "john.doe@example.com"
                  password: "SecurePass123!"
                  confirmPassword: "SecurePass123!"
      responses:
        "201":
          description: User account created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
              examples:
                registeredUser:
                  summary: Successfully registered user
                  value:
                    id: "u_789"
                    name: "John Doe"
                    email: "john.doe@example.com"
                    role: "customer"
                    createdAt: "2024-03-23T10:30:00Z"
                    emailVerified: false
        "400":
          description: Invalid registration data
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                weakPassword:
                  summary: Password too weak
                  value:
                    code: "WEAK_PASSWORD"
                    message: "Password must contain at least 8 characters with uppercase, lowercase, number, and special character"
        "409":
          description: Email already exists
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                emailExists:
                  summary: Email already registered
                  value:
                    code: "EMAIL_EXISTS"
                    message: "An account with this email address already exists"

  /users/login:
    post:
      tags: [Users]
      summary: User authentication
      description: |
        Authenticates a user with email and password credentials. Returns a JWT token
        that must be included in subsequent API requests requiring authentication.
        Tokens expire after 24 hours.
      operationId: loginUser
      requestBody:
        required: true
        description: User login credentials
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LoginRequest"
            examples:
              userLogin:
                summary: User login
                value:
                  email: "john.doe@example.com"
                  password: "SecurePass123!"
      responses:
        "200":
          description: Login successful
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LoginResponse"
              examples:
                successfulLogin:
                  summary: Successful authentication
                  value:
                    token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1Xzc4OSIsIm5hbWUiOiJKb2huIERvZSIsImlhdCI6MTUxNjIzOTAyMiwiZXhwIjoxNTE2MzI1NDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
                    user:
                      id: "u_789"
                      name: "John Doe"
                      email: "john.doe@example.com"
                      role: "customer"
                    expiresIn: 86400
        "400":
          description: Invalid login data
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                invalidCredentials:
                  summary: Wrong email or password
                  value:
                    code: "INVALID_CREDENTIALS"
                    message: "Invalid email or password"
        "429":
          description: Too many login attempts
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                rateLimited:
                  summary: Rate limit exceeded
                  value:
                    code: "RATE_LIMITED"
                    message: "Too many login attempts. Please try again in 15 minutes"

  /users/profile:
    get:
      tags: [Users]
      summary: Get user profile
      description: Retrieves the profile information for the authenticated user
      operationId: getUserProfile
      security:
        - BearerAuth: []
      responses:
        "200":
          description: User profile retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    Book:
      type: object
      required: [id, title, author, genre, price, stock]
      properties:
        id:
          type: string
          description: Unique identifier for the book
          pattern: '^b_[a-zA-Z0-9]+$'
          example: "b_123"
        title:
          type: string
          description: Book title
          minLength: 1
          maxLength: 255
          example: "The Great Gatsby"
        author:
          type: string
          description: Author name
          minLength: 1
          maxLength: 255
          example: "F. Scott Fitzgerald"
        genre:
          type: string
          description: Book genre/category
          enum: [fiction, non-fiction, mystery, romance, sci-fi, fantasy, biography, history, science, technology]
          example: "fiction"
        price:
          type: number
          format: float
          description: Book price in USD
          minimum: 0
          example: 12.99
        stock:
          type: integer
          description: Available quantity in inventory
          minimum: 0
          example: 42
        isbn:
          type: string
          description: International Standard Book Number
          pattern: '^978-[0-9]{1}-[0-9]{3}-[0-9]{5}-[0-9]{1}$'
          example: "978-0-7432-7356-5"
        publishedDate:
          type: string
          format: date
          description: Publication date
          example: "1925-04-10"
        description:
          type: string
          description: Book description
          maxLength: 1000
          example: "A classic American novel set in the Jazz Age, exploring themes of wealth, love, and the American Dream."
        publisher:
          type: string
          description: Publisher name
          maxLength: 255
          example: "Scribner"
        pages:
          type: integer
          description: Number of pages
          minimum: 1
          example: 180
        language:
          type: string
          description: Book language
          example: "English"
        createdAt:
          type: string
          format: date-time
          description: When the book was added to the catalog
          example: "2024-01-15T10:30:00Z"
        updatedAt:
          type: string
          format: date-time
          description: When the book information was last updated
          example: "2024-03-20T14:45:00Z"

    CreateBookRequest:
      type: object
      required: [title, author, genre, price, stock, isbn]
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 255
          example: "The Catcher in the Rye"
        author:
          type: string
          minLength: 1
          maxLength: 255
          example: "J.D. Salinger"
        genre:
          type: string
          enum: [fiction, non-fiction, mystery, romance, sci-fi, fantasy, biography, history, science, technology]
          example: "fiction"
        price:
          type: number
          format: float
          minimum: 0
          example: 13.99
        stock:
          type: integer
          minimum: 0
          example: 25
        isbn:
          type: string
          pattern: '^978-[0-9]{1}-[0-9]{3}-[0-9]{5}-[0-9]{1}$'
          example: "978-0-316-76948-0"
        publishedDate:
          type: string
          format: date
          example: "1951-07-16"
        description:
          type: string
          maxLength: 1000
          example: "A controversial novel about teenage rebellion and alienation"
        publisher:
          type: string
          maxLength: 255
          example: "Little, Brown and Company"
        pages:
          type: integer
          minimum: 1
          example: 277
        language:
          type: string
          default: "English"
          example: "English"

    BookListResponse:
      type: object
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Book"
        pagination:
          $ref: "#/components/schemas/PaginationInfo"

    PaginationInfo:
      type: object
      required: [page, limit, total, totalPages, hasNext, hasPrev]
      properties:
        page:
          type: integer
          description: Current page number
          example: 1
        limit:
          type: integer
          description: Items per page
          example: 20
        total:
          type: integer
          description: Total number of items
          example: 156
        totalPages:
          type: integer
          description: Total number of pages
          example: 8
        hasNext:
          type: boolean
          description: Whether there is a next page
          example: true
        hasPrev:
          type: boolean
          description: Whether there is a previous page
          example: false

    Order:
      type: object
      required: [id, userId, items, subtotal, tax, shipping, total, status, createdAt]
      properties:
        id:
          type: string
          description: Unique order identifier
          pattern: '^ord_[a-zA-Z0-9]+$'
          example: "ord_456"
        userId:
          type: string
          description: ID of the user who placed the order
          example: "u_789"
        items:
          type: array
          description: List of ordered items
          minItems: 1
          items:
            $ref: "#/components/schemas/OrderItem"
        subtotal:
          type: number
          format: float
          description: Subtotal before tax and shipping
          minimum: 0
          example: 25.98
        tax:
          type: number
          format: float
          description: Tax amount
          minimum: 0
          example: 2.08
        shipping:
          type: number
          format: float
          description: Shipping cost
          minimum: 0
          example: 5.99
        total:
          type: number
          format: float
          description: Total order amount
          minimum: 0
          example: 34.05
        status:
          type: string
          description: Current order status
          enum: [pending, confirmed, shipped, delivered, cancelled]
          example: "pending"
        shippingAddress:
          $ref: "#/components/schemas/Address"
        trackingNumber:
          type: string
          description: Shipping tracking number (available when shipped)
          example: "1Z999AA1234567890"
        createdAt:
          type: string
          format: date-time
          description: When the order was created
          example: "2024-03-23T10:30:00Z"
        updatedAt:
          type: string
          format: date-time
          description: When the order was last updated
          example: "2024-03-23T11:15:00Z"
        estimatedDelivery:
          type: string
          format: date-time
          description: Estimated delivery date
          example: "2024-03-30T00:00:00Z"

    OrderItem:
      type: object
      required: [bookId, quantity, unitPrice, subtotal]
      properties:
        bookId:
          type: string
          description: ID of the ordered book
          example: "b_123"
        bookTitle:
          type: string
          description: Title of the book (for display purposes)
          example: "The Great Gatsby"
        quantity:
          type: integer
          description: Quantity ordered
          minimum: 1
          example: 2
        unitPrice:
          type: number
          format: float
          description: Price per unit at time of order
          minimum: 0
          example: 12.99
        subtotal:
          type: number
          format: float
          description: Total for this item (quantity × unitPrice)
          minimum: 0
          example: 25.98

    Address:
      type: object
      required: [street, city, state, zipCode, country]
      properties:
        street:
          type: string
          description: Street address
          example: "123 Main St"
        city:
          type: string
          description: City name
          example: "New York"
        state:
          type: string
          description: State or province
          example: "NY"
        zipCode:
          type: string
          description: ZIP or postal code
          example: "10001"
        country:
          type: string
          description: Country name
          example: "USA"

    OrderListResponse:
      type: object
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Order"
        pagination:
          $ref: "#/components/schemas/PaginationInfo"

    CreateOrderRequest:
      type: object
      required: [items, shippingAddress]
      properties:
        items:
          type: array
          description: List of books to order
          minItems: 1
          items:
            type: object
            required: [bookId, quantity]
            properties:
              bookId:
                type: string
                description: ID of the book to order
                example: "b_123"
              quantity:
                type: integer
                description: Quantity to order
                minimum: 1
                maximum: 10
                example: 2
        shippingAddress:
          $ref: "#/components/schemas/Address"
        notes:
          type: string
          description: Optional order notes
          maxLength: 500
          example: "Please leave at front door if not home"

    User:
      type: object
      required: [id, name, email, role, createdAt]
      properties:
        id:
          type: string
          description: Unique user identifier
          pattern: '^u_[a-zA-Z0-9]+$'
          example: "u_789"
        name:
          type: string
          description: User's full name
          minLength: 1
          maxLength: 100
          example: "John Doe"
        email:
          type: string
          format: email
          description: User's email address
          example: "john.doe@example.com"
        role:
          type: string
          description: User role in the system
          enum: [customer, admin]
          example: "customer"
        emailVerified:
          type: boolean
          description: Whether the user's email has been verified
          example: false
        createdAt:
          type: string
          format: date-time
          description: When the user account was created
          example: "2024-03-23T10:30:00Z"
        updatedAt:
          type: string
          format: date-time
          description: When the user account was last updated
          example: "2024-03-23T10:30:00Z"

    RegisterRequest:
      type: object
      required: [name, email, password, confirmPassword]
      properties:
        name:
          type: string
          description: User's full name
          minLength: 1
          maxLength: 100
          example: "John Doe"
        email:
          type: string
          format: email
          description: User's email address (must be unique)
          example: "john.doe@example.com"
        password:
          type: string
          format: password
          description: User's password (min 8 chars, must include uppercase, lowercase, number, special char)
          minLength: 8
          example: "SecurePass123!"
        confirmPassword:
          type: string
          format: password
          description: Password confirmation (must match password)
          minLength: 8
          example: "SecurePass123!"

    LoginRequest:
      type: object
      required: [email, password]
      properties:
        email:
          type: string
          format: email
          description: User's email address
          example: "john.doe@example.com"
        password:
          type: string
          format: password
          description: User's password
          example: "SecurePass123!"

    LoginResponse:
      type: object
      required: [token, user, expiresIn]
      properties:
        token:
          type: string
          description: JWT authentication token
          example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1Xzc4OSIsIm5hbWUiOiJKb2huIERvZSIsImlhdCI6MTUxNjIzOTAyMiwiZXhwIjoxNTE2MzI1NDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
        user:
          $ref: "#/components/schemas/User"
        expiresIn:
          type: integer
          description: Token expiration time in seconds
          example: 86400

    Error:
      type: object
      required: [code, message]
      properties:
        code:
          type: string
          description: Error code for programmatic handling
          example: "VALIDATION_ERROR"
        message:
          type: string
          description: Human-readable error message
          example: "The provided data is invalid"
        details:
          type: object
          description: Additional error details (optional)
          additionalProperties: true
          example:
            field: "email"
            reason: "Email format is invalid"
        timestamp:
          type: string
          format: date-time
          description: When the error occurred
          example: "2024-03-23T10:30:00Z"