Skip to main content

​
Overview

The Products API provides endpoints for managing the product catalog, including CRUD operations, search, filtering, and image gallery management. Base URL: /api/productos Source: ProductController.java

​
Authentication

  • Public endpoints: GET requests (list, search, view)
  • Admin-only endpoints: POST, PUT, DELETE operations require ROLE_ADMIN

​
Endpoints

​
List All Products

GET /api/productos
Retrieve all products in the catalog (including inactive products). Authentication: None (public endpoint) Response: 200 OK
​
products
array
Array of product objects
Example Request: 
curl -X GET http://localhost:8080/api/productos

​
List Active Products

GET /api/productos/activos
Retrieve only active products (where activo = true). Authentication: None (public endpoint) Response: 200 OK - Array of active product objects 
GET /api/productos/destacados
Retrieve products marked as featured (destacado = true). Authentication: None (public endpoint) Response: 200 OK - Array of featured product objects Use Case: Display featured products on the homepage or promotional sections.

​
Get Product by ID

GET /api/productos/{id}
Authentication: None (public endpoint)
​
id
long
required
Product ID
Responses:
  • 200 OK - Product object
  • 404 Not Found - Product does not exist
Example Request:
cURL
curl -X GET http://localhost:8080/api/productos/1

​
Search Products by Name

GET /api/productos/buscar?nombre={query}
Search products by name (case-insensitive partial match). Authentication: None (public endpoint)
​
nombre
string
required
Search query string
Response: 200 OK - Array of matching products Example Request:
cURL
curl -X GET "http://localhost:8080/api/productos/buscar?nombre=laptop"

​
List Products by Category

GET /api/productos/categoria/{id}
Retrieve all products in a specific category. Authentication: None (public endpoint)
​
id
long
required
Category ID
Response: 200 OK - Array of products in the category

​
Get Similar Products

GET /api/productos/{id}/similares
Retrieve products similar to the specified product (based on category). Authentication: None (public endpoint)
​
id
long
required
Product ID
Response: 200 OK - Array of similar products Use Case: Display “You may also like” or “Related products” sections.

​
Create Product

POST /api/productos
Authentication: Required - ROLE_ADMIN Request Body:
​
nombre
string
required
Product name
​
descripcion
string
required
Product description
​
precio
double
required
Product price
​
stock
integer
required
Initial stock quantity
​
categoria
object
required
Category object with id field
​
destacado
boolean
Featured flag (default: false)
Response: 200 OK - Created product object with generated ID and slug Example Request:
cURL
curl -X POST http://localhost:8080/api/productos \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Laptop Dell XPS 15",
    "descripcion": "High-performance laptop with Intel i7",
    "precio": 1299.99,
    "stock": 10,
    "categoria": {"id": 1},
    "destacado": true
  }'
The system automatically generates a URL-friendly slug from the product name (e.g., “laptop-dell-xps-15”).

​
Update Product

PUT /api/productos/{id}
Authentication: Required - ROLE_ADMIN
​
id
long
required
Product ID to update
Request Body: Same as Create Product (all fields) Responses:
  • 200 OK - Updated product object
  • 404 Not Found - Product does not exist
PUT /api/productos/{id}/galeria
Update the image gallery for a product. This endpoint replaces all existing images. Authentication: Required - ROLE_ADMIN
​
id
long
required
Product ID
Request Body: Array of image URL strings Example Request:
cURL
curl -X PUT http://localhost:8080/api/productos/1/galeria \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    "https://example.com/images/product1-front.jpg",
    "https://example.com/images/product1-back.jpg",
    "https://example.com/images/product1-detail.jpg"
  ]'
Response: 200 OK 
{
  "message": "Galería actualizada correctamente"
}
This operation uses orphan removal - any images not included in the new array will be permanently deleted from the database.

​
Soft Delete Product

DELETE /api/productos/{id}
Soft delete a product by setting activo = false. The product remains in the database but is hidden from public listings. Authentication: Not specified (should be admin-only in production)
​
id
long
required
Product ID
Response: 200 OK 
{
  "message": "Estado del producto actualizado"
}

​
Permanently Delete Product

DELETE /api/productos/{id}/definitivo
Permanently remove a product from the database. Authentication: Required - ROLE_ADMIN
​
id
long
required
Product ID
Response: 204 No Content
This action is irreversible. All associated data (images, order details) will be affected. Use soft delete unless absolutely necessary.

​
Error Responses

Status CodeDescription
400 Bad RequestInvalid request body or parameters
401 UnauthorizedMissing or invalid JWT token
403 ForbiddenUser does not have ROLE_ADMIN
404 Not FoundProduct does not exist
500 Internal Server ErrorServer error

​
Integration Examples

​
Frontend: Display Product Catalog

JavaScript
async function loadProducts() {
  const response = await fetch('http://localhost:8080/api/productos/activos');
  const products = await response.json();
  
  products.forEach(product => {
    console.log(`${product.nombre} - $${product.precio}`);
    console.log(`Stock: ${product.stock}`);
  });
}

​
Admin: Add New Product

JavaScript
async function createProduct(productData, token) {
  const response = await fetch('http://localhost:8080/api/productos', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(productData)
  });
  
  return response.json();
}

Categories API

Manage product categories

Cart API

Add products to shopping cart

Build docs developers (and LLMs) love

Get started for freeTalk to us