Skip to main content

First Products Endpoint, Clear Localization Rules & Predictable API Responses

· 2 min read
Albert Tiñena
Albert Tiñena
Chief Technology Officer (CTO)
David Sancho
David Sancho
Principal Engineer & Technical Architect

After a few months of groundwork and internal alignment, we’re shipping one of the most important milestones of the OpenTiendas API so far: the first Products endpoint is live.

Alongside it, we’ve formalized and documented the core rules around localization, markets, field selection, and response shape that apply consistently across the API.

First catalog endpoint: Get Product​

We’ve released the first Products API endpoint:

GET /api/v1/products/{id}

This endpoint supports both simple products and products with variants.

Key characteristics:

  • One endpoint for simple and multi-variant products
  • Explicit and unambiguous schema
  • Deterministic localization and pricing behavior
  • Safe defaults for performance (variants preview capped at 50)

This endpoint establishes the baseline design for all future catalog endpoints.

No more Accept-Language​

The Accept-Language header has been removed.

Localization is now controlled exclusively via the locales query parameter:

GET /api/v1/products/123?locales=es-ES,fr-FR
  • Multiple locales can be requested in a single call
  • All translatable fields are returned only under translations
  • This behavior is consistent across Products, Categories, Brands, and Reviews

Locale → Market → Prices​

In OpenTiendas, a locale represents more than language.

  • Each locale deterministically resolves to one pricing market
  • Prices are returned under prices, keyed by market identifiers (market_es, market_fr, …)
  • Multiple locales may resolve to the same market

This relationship is now explicitly documented and enforced.

👉 Localization & Markets

Fixed fields, default fields, explicit expansion​

All API resources now follow the same field model:

  • Fixed fields are always returned (e.g. id)
  • Default fields form the minimal canonical representation
  • When fields is specified, only:
    • fixed fields, and
    • explicitly requested fields
      are returned

Each resource documents its fixed fields, default fields, and navigable relationships.

One rule for missing, empty, and null​

The API enforces a single data presence contract everywhere:

  • Missing field → not applicable
  • Empty value ("", [], {}) → applicable but empty
  • null → explicitly unset or unknown

This removes ambiguity and simplifies client-side logic.

What’s next​

  • Product list endpoints
  • Expanded variants access
  • Continued alignment across resources for filtering

These changes lay the foundation for a predictable, scalable catalog API.

👉 API Overview
👉 Localization & Markets