API Design Question: E-commerce Product Catalog

Let's design a simplified API for an e-commerce product catalog. Imagine you're building the backend for a website like Amazon or Etsy, focusing specifically on how products are stored and retrieved. This API will allow client applications (like web browsers or mobile apps) to browse, search, and view product details.

1. Define the Core Entities: What are the essential attributes of a Product? Consider attributes like product_id, name, description, price, category, image_url, and inventory_count. Are there other attributes you would include? Justify your choices.

2. Design the API Endpoints: Propose the main API endpoints for interacting with the product catalog. Focus on the following functionalities. Provide example requests and responses (in JSON format) for each endpoint:

   • Retrieve a product by ID: (/products/{product_id})
   • Search for products: (/products?keyword=example&category=example)
   • List products by category: (/categories/{category_name}/products)

3. Considerations:

   • How would you handle pagination for large product lists?
   • How would you implement filtering and sorting options in the search endpoint? (e.g., filter by price range, sort by popularity).
   • How would you handle different image sizes and formats?

Example Scenario: A user searches for "red shoes" on the website. Describe how the API would be used to fulfill this request, including the specific endpoint called, the parameters passed, and the format of the expected response.

API Design Question: E-commerce Product Catalog

Let's design a simplified API for an e-commerce product catalog.

1. Core Entities

The essential attributes of a Product would include:

• product_id (UUID): A unique identifier for each product.
• name (String): The name of the product.
• description (String): A detailed description of the product.
• price (Number): The price of the product.
• category (String): The category the product belongs to.
• image_url (String): A URL pointing to the product image.
• inventory_count (Integer): The number of units currently in stock.
• brand (String): The brand of the product.
• attributes (JSON): Key-value pairs for product-specific attributes (e.g., color, size, material).
• rating (Number): Average rating of the product based on user reviews.
• num_reviews (Integer): Number of reviews for the product.
• created_at (Timestamp): When the product was first added to the catalog.
• updated_at (Timestamp): When the product was last updated.

Justification:

• product_id is crucial for uniquely identifying each product.
• name, description, price, category, and image_url are fundamental for displaying product information to users.
• inventory_count is essential for managing stock levels and preventing overselling.
• brand helps users filter and search for products from specific brands.
• attributes allows for storing product-specific details that vary across categories.
• rating and num_reviews provide social proof and help users make informed decisions.
• created_at and updated_at are useful for tracking product lifecycle and changes.

2. API Endpoints

Retrieve a product by ID

• Endpoint: GET /products/{product_id}

• Example Request:

  GET /products/a1b2c3d4-e5f6-7890-1234-567890abcdef
  

• Example Response:

  {
    "product_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "name": "Red Running Shoes",
    "description": "High-performance running shoes for all terrains.",
    "price": 99.99,
    "category": "Shoes",
    "image_url": "https://example.com/images/red_shoes.jpg",
    "inventory_count": 50,
    "brand": "Nike",
    "attributes": {
      "color": "Red",
      "size": "10",
      "material": "Mesh"
    },
    "rating": 4.5,
    "num_reviews": 120,
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-15T00:00:00Z"
  }
  

Search for products

• Endpoint: GET /products

• Example Request:

  GET /products?keyword=shoes&category=Running&min_price=50&max_price=150&sort_by=popularity&sort_order=desc&page=2&page_size=20
  

• Example Response:

  {
    "products": [
      {
        "product_id": "p1",
        "name": "Nike Air Zoom Running Shoes",
        "description": "...",
        "price": 120.00,
        "category": "Running",
        "image_url": "...",
        "inventory_count": 30
      },
      {
        "product_id": "p2",
        "name": "Adidas Adizero Running Shoes",
        "description": "...",
        "price": 110.00,
        "category": "Running",
        "image_url": "...",
        "inventory_count": 25
      }
    ],
    "total_count": 150,
    "page": 2,
    "page_size": 20
  }
  

List products by category

• Endpoint: GET /categories/{category_name}/products

• Example Request:

  GET /categories/Shoes/products?page=1&page_size=10
  

• Example Response:

  {
    "products": [
      {
        "product_id": "s1",
        "name": "Leather Boots",
        "description": "...",
        "price": 150.00,
        "category": "Shoes",
        "image_url": "...",
        "inventory_count": 15
      },
      {
        "product_id": "s2",
        "name": "Suede Loafers",
        "description": "...",
        "price": 80.00,
        "category": "Shoes",
        "image_url": "...",
        "inventory_count": 40
      }
    ],
    "total_count": 50,
    "page": 1,
    "page_size": 10
  }
  

3. Considerations

Pagination

Pagination can be implemented using page and page_size query parameters. The API should return the total_count of products matching the query, allowing clients to calculate the total number of pages.

Filtering and Sorting

Filtering and sorting can be implemented using query parameters in the search endpoint (/products).

• Filtering:
  • min_price: Minimum price.
  • max_price: Maximum price.
  • category: Product category.
  • brand: Product brand.
  • color: Product color.
  • size: Product size.
• Sorting:
  • sort_by: Field to sort by (e.g., price, popularity, rating).
  • sort_order: Sort order (asc or desc).

Image Handling

Different image sizes and formats can be handled by:

1. Storing multiple image versions: Store multiple versions of each image (e.g., thumbnail, medium, large) with different sizes and formats.
2. Using a CDN: Use a Content Delivery Network (CDN) to serve images from geographically distributed servers, improving performance and reducing latency.
3. Image resizing on the fly: Use an image processing service that can resize and convert images on demand based on the requested parameters.

Example Scenario: User searches for "red shoes"

1. The user enters "red shoes" in the search bar on the website.
2. The client-side application makes a request to the /products endpoint with the following parameters:

   GET /products?keyword=red shoes
   

3. The API processes the request, searches the product catalog for products matching the keyword "red shoes".
4. The API returns a JSON response containing a list of products that match the search query, along with pagination information (total count, current page, page size).

   {
     "products": [
       {
         "product_id": "rs1",
         "name": "Red Leather Shoes",
         "description": "...",
         "price": 100.00,
         "category": "Shoes",
         "image_url": "...",
         "inventory_count": 20
       },
       {
         "product_id": "rs2",
         "name": "Red Suede Shoes",
         "description": "...",
         "price": 90.00,
         "category": "Shoes",
         "image_url": "...",
         "inventory_count": 30
       }
     ],
     "total_count": 5,
     "page": 1,
     "page_size": 20
   }
   

5. The client-side application displays the search results to the user.