Mercado Libre #Challenge

Task

Build a simplified backed API that supplies product details for use in an item comparison feature.
Follow established backend best practices, providing clear and efficient endpoints to retrieve the required data for product comparisons.

Overview

This API provides a system to manage and compare product models, enabling advanced querying, filtering, and ranking of items based on both standard attributes and custom specifications.

It is designed to support use cases such as product discovery, side-by-side comparisons, and decision-making workflows where multiple criteria (e.g., price, performance, features) must be evaluated together.

The API exposes:

• Model management endpoints for creating and deleting product models.
• Public read endpoints for retrieving models with pagination.
• Comparison endpoints that:
  • Return ranked lists of models based on weighted criteria.
  • Generate comparison matrices across multiple models.
  • Support both standard attributes (e.g., price, rating, brand) and dynamic custom specifications (e.g., VRAM, TDP, clock speed).

Key capabilities include:

• Weighted ranking system supporting:
  • Prefer higher
  • Prefer lower
  • Prefer equals
• Flexible filtering with logical expressions (AND/OR grouping).
• Dynamic attributes model allowing extensible product specifications without schema changes.
• Matrix-style comparisons with best/worst indicators per attribute.
• Pagination support for scalable result sets.

This API is intended as a proof of concept (POC) demonstrating how to build a flexible, extensible product comparison engine that can be adapted to different domains.

Compilation

Run:

maven clean install

Test

Run

maven clean test

Coverage

Coverage statistics can be found in /target/site/jacoco/index.html after a successful test is done

Use Cases

1. As a client, I want to retrieve a paginated list of models.
2. As a client, I want to filter the list of models using predefined attributes and custom specs.
3. As a client, I want to rank models using selected ranking criteria.
4. As a client, I want to request only selected predefined model attributes in the list response.
5. As a client, I want to compare a selected set of models in a matrix.
6. As a client, I want the comparison matrix to highlight the best and worst values for comparable rows.

Functional Requirements

FR-1 Retrieve paginated models

1. The system shall allow clients to retrieve a paginated list of product models.

   1. Supports page number and page size
   2. Returns total count or pagination metadata
   3. Default sorting applied if none specified

---

FR-2 Filter models

1. The system shall allow clients to filter models using

   1. Predefined attributes (e.g., price, rating, release date, condition, brand)
   2. Custom specifications (dynamic attributes)

2. The system shall accept filter expressions (RSQL)

3. The system shall validate attribute names and operations

4. The system shall reject unsupported operations or invalid values

---

FR-3 Rank models

1. The system shall allow clients to rank models based on one or more criteria.

   1. Supports multiple ranking criteria (priority order)

   2. Supports operations such as

      • prefer higher
      • prefer lower
      • prefer equals

   3. Applies tie-breaking logic when multiple models have equal scores

---

FR-4 Select response attributes

1. The system shall allow clients to specify which predefined attributes are included in the response.

   1. Only requested attributes shall be returned
   2. Unsupported attributes shall be rejected

---

FR-5 Provide list insights

1. The system shall provide aggregated insights for the result set.

   1. Includes best and worst values for selected attributes
   2. May include summary statistics such as minimum and maximum values
   3. Insights shall be consistent with applied filters and ranking

---

FR-6 Compare selected models

1. The system shall allow clients to request a comparison matrix for a selected set of models.

   1. Accepts a list of model identifiers
   2. Returns models as columns
   3. Returns attributes and specifications as rows

---

FR-7 Select comparison rows

1. The system shall allow clients to specify which rows appear in the comparison matrix.

   1. Supports predefined attributes
   2. Supports custom specifications

---

FR-8 Provide matrix values

1. The system shall provide values for each model in each row.

   1. Values may be null if not available
   2. Values shall include display-ready representations
   3. Values may include raw values for internal processing

---

FR-9 Highlight best and worst values

1. The system shall identify best and worst values for each comparable row.

   1. Based on attribute semantics (e.g., lower price is better)
   2. Supports multiple best or worst values in case of ties

---

FR-10 Provide model comparison scores

1. The system shall compute and return an overall score for each model in the comparison.

   1. Score reflects how well the model satisfies ranking criteria
   2. Score shall be used to order models in the comparison matrix

---

FR-11 Validate filter expressions

1. The system shall validate all filter expressions before execution.

   1. Rejects invalid RSQL syntax
   2. Rejects unknown attributes or specifications
   3. Rejects unsupported operations
   4. Rejects invalid value types

---

FR-12 Validate comparison requests

1. The system shall validate comparison requests.

   1. Rejects empty model lists
   2. Rejects invalid or non-existent model identifiers
   3. Rejects unsupported attribute or specification selections