Facet Endpoints Are Data Contracts for Recipe APIs

The trend worth watching

Facet and statistics endpoints look like small infrastructure details until a product depends on them for search, recommendations, analytics, ingredient normalization, or quality monitoring. In the past week, several Open Food Facts changes made that point unusually concrete.

One merged change now generates JSON versions of product statistics alongside existing HTML statistics files, so clients can reuse the same created_t and completed_t datasets without parsing generated pages. Another Robotoff fix updated calls from older facet paths such as /brands.json to /facets/brands.json, while preserving downstream metric tag names so dashboards would not silently change. A separate OpenAPI documentation change added a validation pattern for image type fields.

The lesson for recipe and food-data products is not merely that URLs change. It is that every facet, statistics file, and validation rule eventually becomes part of a product contract. If a meal-planning app filters by cuisine, a grocery workflow maps ingredients to brands, or a nutrition dashboard tracks completeness by source, those fields need the same care as core recipe endpoints.

Thesis: recipe API teams should model facet outputs, statistics endpoints, and validation constraints as versioned API surfaces with explicit stability, provenance, and migration rules, not as byproducts of search pages or admin dashboards.

The repeated angle this avoids

Recent posts here have already covered ingestion-time facets, ingredient taxonomy drift, salt and sodium data-quality checks, receipt privacy, sustainability provenance, and unwanted-ingredient filters. The angle to avoid is "normalize fields before search." That remains true, but this post is about a different layer: once normalized fields are published as facets, aggregate statistics, SDK-visible schemas, or operational metrics, they become integration contracts that can break clients even when the underlying recipe data is correct.

That distinction matters for API buyers. A recipe API can have clean ingredient entities and still be hard to operate if facet paths move without redirects, aggregate counts are only available inside HTML, validation constraints are hidden in code, or metric names shift after a migration.

Why JSON statistics are more than a convenience

HTML statistics pages are useful for humans. JSON statistics endpoints are useful for systems. The Open Food Facts change to generate JSON files for product statistics is a good example because it exposes graph datasets directly instead of making clients scrape the generated HTML.

For recipe API builders, this pattern applies to several common product surfaces:

• catalog freshness by source
• percentage of recipes with normalized ingredients
• nutrition completeness by nutrient and geography
• missing serving-size rates
• allergen or diet-claim coverage
• grocery-match coverage by retailer or region
• AI extraction confidence distributions
• recipe ingestion volume by partner feed

If those statistics are only embedded in dashboards, they are hard to reuse. Product managers cannot easily drive experiments from them, customers cannot build trust reports, and support teams cannot answer whether a tenant's catalog quality is improving. If they are exposed as JSON with stable keys, they become operational data.

A simple statistics endpoint should not return screenshots, table fragments, or display labels as the only identifiers. It should return typed measures with time windows, source scopes, and generation metadata:

{
  "metric": "recipe_ingredient_normalization_completion",
  "scope": {
    "tenantId": "demo",
    "locale": "en-US",
    "source": "partner_feed"
  },
  "window": {
    "start": "2026-07-01",
    "end": "2026-07-08",
    "granularity": "day"
  },
  "generatedAt": "2026-07-08T00:15:00Z",
  "schemaVersion": "2026-07-08",
  "points": [
    { "date": "2026-07-01", "totalRecipes": 18420, "completedRecipes": 17102 },
    { "date": "2026-07-02", "totalRecipes": 18511, "completedRecipes": 17280 }
  ]
}

The product decision is not whether to copy this exact shape. The decision is whether aggregate food-data quality is available as a reliable machine interface. For teams selling to developers and technical buyers, that reliability can be a differentiator.

Facet URL migrations can break quiet dependencies

The Robotoff fix is a useful warning because it was not about a flashy user-facing feature. Product Opener had moved facet pages under a /facets/ prefix, and Robotoff still referenced older paths in metrics and brand-list generation jobs. The pull request notes a subtle second-order issue: changing the URL parsing logic could have changed metric tag names from values like states to facets_states, breaking existing dashboards or queries. The fix preserved the old tag names while updating the paths.

Recipe products have the same class of dependency. Consider these apparently minor changes:

Change	Obvious effect	Hidden contract risk
/ingredients/tomato becomes /facets/ingredients/tomato	Cleaner routing	Saved URLs, cache keys, analytics jobs, and client SDK methods may fail.
dairy-free is renamed dairy_free	More consistent naming	Existing filters, alerts, and customer reports may split counts.
Brand facet IDs switch from display names to canonical IDs	Better normalization	Grocery matching improves, but clients relying on old labels lose joins.
Country facet moves from text to ISO code	Better interoperability	Historical dashboards need a mapping layer to compare old and new periods.
Empty facets disappear from responses	Smaller payloads	Clients may interpret absence as unsupported rather than zero results.

These are not reasons to avoid improving the API. They are reasons to publish the migration as an API change rather than treating it as a website cleanup.

A durable recipe API should distinguish at least four identifiers:

• the public URL used to browse a facet;
• the stable facet ID used in API filters;
• the display label localized for users;
• the analytics dimension name used in metrics and historical reports.

When these are collapsed into one string, every cleanup becomes a breaking change.

Validation belongs in the contract, not just the code

The OpenAPI change adding an image type validation pattern points to another practical issue: clients need to know not only which fields exist, but which values are acceptable. Recipe APIs often under-specify this layer.

For example, a recipe image field may appear obvious until clients send jpeg, jpg, image/jpeg, JPEG, webp-large, or a URL with no extension. Ingredient quantity units have the same problem: g, gram, grams, gr, and localized equivalents may all appear in the wild. Diet facets and nutrition fields are even more sensitive because invalid values can become misleading product behavior.

Validation constraints should be documented where developers already integrate:

RecipeFacet:
  type: object
  required: [id, type, label]
  properties:
    id:
      type: string
      pattern: "^[a-z0-9][a-z0-9-]*$"
      description: Stable identifier used in API filters and analytics.
    type:
      type: string
      enum: [ingredient, cuisine, diet, equipment, nutrition, time, retailer]
    label:
      type: string
      description: Human-readable display label; not stable for joins.
    deprecated:
      type: boolean
    replacedBy:
      type: string
      nullable: true

This does not remove the need for server-side validation. It reduces integration ambiguity and makes generated SDKs, test fixtures, and customer QA more accurate.

Product/API decisions to make explicitly

Teams building recipe, nutrition, grocery, or food-AI products should answer these questions before publishing new facets or statistics endpoints.

1. What is stable? Decide whether stability applies to IDs, paths, labels, metric names, or all of them. Labels often need to change; IDs should change rarely.
2. What is versioned? Taxonomy versions, nutrition reference versions, generated-recipe model versions, and statistics schema versions should be visible when they affect interpretation.
3. What is historical? If a facet is renamed, can a customer still query last month's metrics? If not, publish a mapping table.
4. What is localized? Locale-specific labels should not become primary keys. A French ingredient label and an English ingredient label can point to the same canonical ingredient ID.
5. What is tenant-specific? Enterprise food-data products often have customer-specific catalogs. A facet that exists for one tenant may be unsupported for another.
6. What is inferred? Facets derived by AI extraction, taxonomy matching, or heuristic parsing need confidence and provenance fields.
7. What is deprecated? Deprecation should be machine-readable, not buried in release notes.

Failure modes that show up late

Facet contracts usually fail after adoption, not during the initial launch. Watch for these signals:

• customers screenshot dashboards because there is no JSON export;
• search filters and analytics counts disagree because they use different facet IDs;
• SDKs accept values the API later rejects;
• generated recipes cannot be indexed because their facets are not in the catalog taxonomy;
• grocery integrations join on labels and break after localization changes;
• historical reports shift because a metric dimension was renamed;
• clients poll heavyweight search endpoints to compute simple aggregate counts;
• partner feeds introduce new units, image types, or diet labels that pass ingestion but fail downstream.

These are operational failures, not just schema design imperfections. They affect support load, customer trust, and the ability to sell the API as infrastructure.

A practical checklist for recipe API teams

Before shipping a facet or statistics surface, run this checklist:

• Define stable IDs separately from display labels and URLs.
• Publish allowed values and patterns in OpenAPI or equivalent docs.
• Include schemaVersion, generatedAt, and source/provenance metadata in aggregate outputs.
• Support redirects or aliases for moved facet paths.
• Preserve analytics dimension names when URL structure changes, or provide an explicit migration map.
• Mark deprecated facets in responses before removing them.
• Distinguish zero results from unsupported facets.
• Include confidence and extraction source for inferred recipe, ingredient, diet, or grocery facets.
• Test generated recipes, imported recipes, and manually curated recipes against the same facet contract.
• Provide lightweight JSON statistics endpoints instead of forcing customers to parse dashboards.

Where Recipe API positioning fits

For a recipe API, the value is not just returning recipes. It is making recipe data operational: searchable, filterable, explainable, measurable, and safe to integrate into grocery, nutrition, meal-planning, and food-AI workflows. Structured ingredients and nutrition fields are the foundation, but published facets and statistics are the layer customers build product decisions on top of.

That is why API design should treat search facets, aggregate quality metrics, and validation rules as first-class surfaces. The more a customer depends on your data for production decisions, the less acceptable it is for important fields to behave like incidental website routes.

Sources

• Open Food Facts server pull request, July 7, 2026: feat: generate JSON files for product statistics
• Robotoff pull request, July 7, 2026: fix: replace obsolete facet URLs with /facets/ prefix
• Open Food Facts server pull request, July 7, 2026: docs: add validation pattern to image type in openapi spec
• Background: OpenAPI Initiative, Data Types