Full sync and export

Safe full snapshot

To upload the whole catalog and at the same time remove everything that is no longer part of it, open a sync, send the batches with its identifier, and commit at the end.

curl -X POST https://catalog.api.metty.eu/catalog/syncs \
  -H "Authorization: Bearer <SECRET_API_KEY>"

{ "sync_id": "sync_8f2c1d4e5a6b7c8d" }

Send the batches with ?sync=:

curl -X PUT 'https://catalog.api.metty.eu/catalog/products?sync=sync_8f2c1d4e5a6b7c8d' \
  -H "Authorization: Bearer <SECRET_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '[ … ]'

Once every batch is uploaded:

curl -X POST https://catalog.api.metty.eu/catalog/syncs/sync_8f2c1d4e5a6b7c8d/commit \
  -H "Authorization: Bearer <SECRET_API_KEY>"

{ "sync_id": "sync_8f2c1d4e5a6b7c8d", "status": "committed", "kept": 1240, "removed": 37 }

Products that did not arrive during the sync are removed from the database and the index. A PUT without the sync parameter is an ordinary incremental update and does not count towards the sync.

Safeguards

Committing an incomplete snapshot would remove most of the catalog, so we reject it in these cases:

situation	error
the sync contains no products	409 generation_incomplete
the sync covers less than 50 % of the catalog	409 generation_incomplete
the sync is already committed	409 generation_committed
the sync expired without a commit	409 sync_expired
the sync identifier does not exist	404 not_found

If you are shrinking the catalog on purpose (for example after discontinuing half of your range), send {"force": true} in the commit body.

A commit closes the sync. A further write with the same sync_id returns 409 generation_committed, so a snapshot cannot be reopened.

One sync at a time

An e-shop can have only one open sync. While it is open, another POST /catalog/syncs returns 409 sync_in_progress — two overlapping snapshots would otherwise delete each other's products. While the search index of the e-shop is being rebuilt, opening a sync can return 503 index_busy; nothing was opened, repeat the request after Retry-After.

An open sync expires one hour after its last write (or after it was opened, if nothing was written yet). Nothing is deleted when a sync expires; the next POST /catalog/syncs simply opens a new one. A write with ?sync= or a commit of an expired sync returns 409 sync_expired — start a new sync.

Recommended procedure

1. Open a sync and store its identifier.
2. Send the whole catalog in batches of at most 100 products with the ?sync= parameter.
3. Verify that no batch returned an item with status: "error".
4. Commit. If any item failed, do not commit — resend the failed products first.

A working implementation of this procedure is in the examples.

Export

The export is there to verify what state of the catalog Metty actually holds:

curl 'https://catalog.api.metty.eu/catalog/products?page=1&per_page=100' \
  -H "Authorization: Bearer <SECRET_API_KEY>"

{
  "total": 1240,
  "page": 1,
  "per_page": 100,
  "pages": 13,
  "products": [
    {
      "id": "sku-1",
      "name": "Príklepová vŕtačka Bosch",
      "url": "https://eshop.sk/vrtacka",
      "price": 129.9,
      "list_price": 159.9,
      "currency": "EUR",
      "in_stock": true,
      "brand": "Bosch",
      "category": "Náradie > Vŕtačky",
      "description": "Príklepová vŕtačka s reguláciou otáčok.",
      "image": "https://eshop.sk/media/vrtacka.jpg",
      "params": { "farba": "modrá" }
    }
  ]
}

The per_page parameter is clamped to 1–500 (default 100). Products come back in exactly the shape PUT accepts, so an export can be fed straight back in as input.

The export works for an e-shop in feed mode as well — the safeguard against mixing modes applies to writes only.