Real World Example

Endpoint	Purpose
`GET /api/v1/products?category=&minPrice=&maxPrice=&sort=&page=`	Search and filter the listing page
`GET /api/v1/products/{id}`	Product detail page
`POST /api/v1/products`	Seller adds a product (seller portal)
`PATCH /api/v1/products/{id}/stock`	Warehouse updates stock
`DELETE /api/v1/products/{id}`	Seller removes a listing

@RestController
@RequestMapping("/api/v1/products")
public class CatalogController {

    private final ProductService service;

    public CatalogController(ProductService service) { this.service = service; }

    @GetMapping
    public List<Product> search(@RequestParam(required = false) String category,
                                @RequestParam(required = false) BigDecimal minPrice,
                                @RequestParam(required = false) BigDecimal maxPrice,
                                @RequestParam(defaultValue = "price") String sort) {
        return service.search(category, minPrice, maxPrice, sort);
    }

    public record StockChange(int delta) {}

    @PatchMapping("/{id}/stock")
    public ResponseEntity<Product> changeStock(@PathVariable Long id, @RequestBody StockChange change) {
        return service.changeStock(id, change.delta())
                .map(ResponseEntity::ok)
                .orElse(ResponseEntity.notFound().build());
    }
}

Example

curl "localhost:8080/api/v1/products?category=Electronics&maxPrice=1500&sort=price"
curl -X PATCH localhost:8080/api/v1/products/1/stock -H "Content-Type: application/json" -d '{"delta":-2}'

Example output

[{"id":3,"name":"USB-C Cable","description":"1 m braided","price":299.00,"stock":500,"category":"Electronics"},{"id":1,"name":"Wireless Mouse","description":"2.4 GHz, silent clicks","price":799.00,"stock":120,"category":"Electronics"}]
{"id":1,"name":"Wireless Mouse","description":"2.4 GHz, silent clicks","price":799.00,"stock":118,"category":"Electronics"}

Note: The stock endpoint sends a change (delta), not the final number. Two warehouse workers updating at the same time then do not overwrite each other. (Concurrency control in the database is covered in the Hibernate & JPA material.)

A Catalogue API Like Flipkart or Amazon

ShopEase: Search and Stock Endpoints

Example