How an API is used in personalization

The shopper opens a product page
       ↓
Your server → API request to Gravity Field: GET /recommendations?user_id=123&item_id=456
       ↓
Gravity Field → returns JSON with six recommended products
       ↓
Your server → renders HTML with the recommendations → serves the browser

Server-side or client-side

Property JS tag (client-side) REST API (server-side)
Speed of deployment Fast (a day) Needs development (one to two weeks)
Resistance to blockers Vulnerable Resistant
Control over data Limited Full
SEO (recommendations in HTML) No Yes
Suited to A fast start Production at high load

The main endpoints of a personalization API

// Fetch recommendations
GET /v1/recommendations?user_id=USER&context=pdp&item_id=ITEM&limit=6

// Send an event
POST /v1/events
{"event": "purchase", "user_id": "USER", "item_id": "ITEM", "price": 45.00}

// Fetch a user's segments
GET /v1/segments?user_id=USER

Caching recommendations

At high traffic, recommendations are often cached on your own server for 5 to 15 minutes. That
reduces load on the API and response latency, at the cost of a small loss of freshness in the
personalization.

What to agree before integrating

  • Which calls are synchronous. A recommendation request rendered into the page is on the critical
    path and needs a hard timeout with a fallback; an event write is not and can be queued.
  • Idempotency of writes. Events sent twice after a network retry must not be counted twice.
  • Error semantics. Decide in advance what the page shows when the API is unavailable — a
    non-personalized block beats an empty one.
  • Versioning. A pinned API version protects the integration from breaking changes on the
    platform side.