SYSTEM Cited by 1 source
Zalando Catalog API¶
Identity¶
Catalog API is the top-of-stack presentation layer in Zalando's catalog-search substrate. It "coordinates everything that has to happen for a single 'search' in the app" (sources/2025-12-16-zalando-the-day-our-own-queries-dosed-us-inside-zalando-search) — one inbound request from the app becomes many outbound ES queries plus decisions about which page to return.
Responsibilities¶
- 1→N fan-out to Base Search. A single user "search" is translated into multiple queries to Base Search via the NER query builder — for the main result set, for facets, for product counts, for related-content lookups.
- A/B-test integration. Different users or cohorts may trigger slightly different query shapes, because Catalog API routes requests through Zalando's experimentation platform so cohort membership can alter the query it issues.
- Redirect decisions. Catalog API owns "the 'final redirect' decisions — for example, whether a query should land on a generic search result page or on dedicated landing pages."
- Separate facets query per search. For every search, Catalog API issues a separate Elasticsearch call to fetch the filters (brand, size, colour, price-bucket) for that query. These are aggregation-heavy queries and stress Elasticsearch differently than plain document retrieval — the failure surface that the 2025-12-16 incident exploited.
- Top-of-stack cache. Catalog API "caches popular queries and filter combinations" to absorb repeat traffic before it reaches NER / Base Search.
Role as a presentation-layer control plane¶
In incident response, Catalog API acts as the fast-operator control surface on the search path — a presentation layer that doubles as an admission / load-shedding control. The 2025-12-16 incident's 5-lever cocktail included three app-side levers that operate at Catalog API + Search API:
"On the application side, the presentation layers were used as a control plane to reduce load on downstream systems: we turned off non-critical calls, reduced the number of parallel queries per request, and increased cache effectiveness for hot queries and filter combinations. Our search steering configuration also played a key role here: we lowered the load generated by search by sampling fewer requests into some heavier ML model integrations and promotion-enrichment flows, falling back to simpler ranking where needed."
This is the canonical "presentation-layer-as-control-plane" shape — the same layer that normally enriches experiences is, in incidents, the layer that sheds them. Structural kin of load shedding at ingestion.
Seen in¶
- sources/2025-12-16-zalando-the-day-our-own-queries-dosed-us-inside-zalando-search
— canonical wiki instance. Catalog API's 1→N fan-out shape
and its separate-facets-query-per-search discipline are both
load-bearing for the incident's failure mode: facets bypass
the main-result-set caches and go to a different ES path that
search_workerparallelisation doesn't accelerate for high-cardinality fields.