Public API

Aktuální a deklarované endpointy

V app/routes/api.php jsou dnes definované tyto endpointy:

  • GET /api/v1/products
  • GET /api/v1/products/{id}
  • GET /api/v1/products/{id}/variants
  • GET /api/v1/categories
  • GET /api/v1/categories/{id}
  • GET /api/v1/brands
  • GET /api/v1/brands/{id}
  • GET /api/v1/search

Co je reálně implementováno

Podle aktuálního kódu jsou dnes implementovány tyto controllery:

  • ProductController
  • CategoryController
  • BrandController
  • SearchController

Public API tedy dnes reálně obsluhuje:

  • listing produktů,
  • detail produktu,
  • seznam variant produktu,
  • listing kategorií,
  • detail kategorie včetně breadcrumbů,
  • listing značek,
  • detail značky,
  • fulltextové hledání přes Meilisearch.

Response format

API vrací JSON v konzistentním tvaru:

{ "data": [...] }

{ "data": {...} }

{ "error": "Not found" }

U listingu produktu je navíc meta s paginací.

Parametry listingu produktu

Podle ProductController::index() lze použít:

  • locale, výchozí cs,
  • page, výchozí 1,
  • limit, výchozí 20, maximum 100.

Viditelnost produktů

Public produktové endpointy vrací pouze produkty ve stavu published.

To se týká:

  • GET /api/v1/products,
  • GET /api/v1/products/{id},
  • GET /api/v1/products/{id}/variants.

Public API tedy nepodporuje query param status a nevrací draft, hidden ani jiné interní workflow stavy.

Parametry dalších endpointů

Categories

  • GET /api/v1/categories
  • locale, výchozí cs
  • page, výchozí 1
  • limit, výchozí 200, maximum 500
  • GET /api/v1/categories/{id}
  • locale, výchozí cs

Vrací pouze aktivní a neinterní kategorie.

Brands

  • GET /api/v1/brands
  • locale, výchozí cs
  • page, výchozí 1
  • limit, výchozí 20, maximum 100
  • GET /api/v1/brands/{id}
  • locale, výchozí cs
  • GET /api/v1/search
  • q, povinný parametr
  • locale, výchozí cs
  • page, výchozí 1
  • limit, výchozí 20, maximum 100

Při nedostupném Meilisearch vrací endpoint 503 Search unavailable.

Důležitá omezení současné implementace

  • lokalizace produktu a kategorií dnes nemá serverový fallback, repository čtou přesný locale,
  • brand má fallback na base data z catalog.brand, protože značka má základní jméno a slug i mimo translation tabulku,
  • detailové endpointy validují UUID,
  • variants vrací jen základní variantová data a lokalizovaný název,
  • search je read vrstva nad Meilisearch, ne zdroj pravdy,
  • pricing, inventory a širší content data zatím nejsou součástí public produktu response.