How to Build a Recommendation API (Playbook)

Recommendation systems are judged in milliseconds and measured in months. The API must return relevant items within a strict latency budget, and the system must prove in controlled experiments that it moves a business metric. This playbook covers building a recommendation API that does both, following FISTA's AI enablement practice. Foundations are in how to build a recommendation system and recommendation system development.

What does the API do?

Stage	Function	Latency
Request	User, context, placement, constraints
Feature lookup	User and context features from the feature store	Milliseconds
Candidate generation	Hundreds of candidates from several retrievers	Milliseconds
Ranking	Model scores candidates on the objective	Milliseconds
Business logic	Rules, diversity, freshness, exclusions	Milliseconds
Response and logging	Items with reasons; impression logs

Step 1: Define the objective and constraints

Agree with product the objective the ranker optimizes (conversion, revenue, watch time quality, retention proxies), the constraints (diversity, freshness, exclusions, fairness, business rules), the placements, and the latency budget per placement. Define the offline metrics that guide iteration and the online metrics that decide. See how to write acceptance criteria for ai.

Step 2: Assemble signals and features

Collect interaction events (views, clicks, purchases, dwell, skips), catalog attributes and content, user profile and context, and impression logs from the API itself. Build a feature store serving both training and online lookup consistently. See how to build a feature store and how to build a data pipeline for ai.

Step 3: Build candidate generators

Implement several retrievers and union their results: collaborative filtering from interaction history, embedding similarity from content and behavior, popularity within segments, and rule-based sources such as recently viewed or trending. Use approximate nearest neighbor indexes for embeddings. Retrieval concepts are in what are embeddings and what is a vector database.

Step 4: Train the ranker

Train a ranking model on logged impressions and outcomes with features from user, item, context, and candidate source, optimizing the agreed objective and correcting for position and exposure bias. Evaluate offline on held-out interactions with ranking metrics by segment. Model practice is in how to build a predictive model.

Step 5: Apply business logic

After ranking, apply rules: exclusions, diversity and category caps, freshness boosts, inventory and eligibility constraints, and fairness adjustments. Keep rules explicit and versioned; they encode product decisions the model does not know. Attach reason codes for explanation.

Step 6: Serve within the latency budget

Precompute what can be precomputed (embeddings, per-user candidate sets, popularity), compute online what depends on context, cache aggressively with sensible invalidation, and define fallbacks (popularity or cached results) when components time out. Load-test at peak. Architecture patterns are in batch vs real-time inference and web app scalability.

Step 7: Experiment online

Run controlled experiments on the business objective with proper randomization and duration, comparing ranker versions, candidate mixes, and business rules. Offline gains that do not replicate online are common; the experiment decides. Design guidance is in the AI ROI measurement framework whitepaper.

Step 8: Monitor

Track latency percentiles, fallback rates, relevance metrics on sampled traffic, coverage of the catalog, diversity, cold-start performance, drift in interaction patterns, and fairness across user and item groups. Retrain on schedule and on drift. See the AI observability whitepaper.

Worked example: a marketplace home feed

A marketplace builds a recommendation API for its home feed with a strict latency budget. Candidate generators combine embedding similarity from browsing history, collaborative filtering, and segment popularity, with a freshness retriever for new listings. The ranker optimizes a blend of purchase probability and long-term engagement defined with product, corrected for position bias. Business rules cap items per seller, enforce category diversity, and exclude out-of-stock listings. Per-user candidate sets are precomputed nightly and refreshed online from session context; cached popularity serves as fallback. A controlled experiment against the previous heuristic feed shows improvement on the objective; a second experiment on a diversity rule shows a small short-term dip and a longer-term retention gain, which product accepts. Monitoring later flags declining coverage for new listings, addressed by tuning the freshness retriever.

What does it cost to run?

Cost scales with request volume, catalog size, and online computation; precomputation and caching shift cost from serving to batch. Value is measured in the experiment-proven lift on the business objective. Drivers are in recommendation system cost.

What are the common mistakes?

• Optimizing click-through and harming the business metric.
• One retriever, so recommendations are narrow.
• Ranking on features unavailable at serving time.
• No fallbacks, so a slow component takes down the page.
• Shipping on offline metrics without experiments.
• Ignoring coverage and diversity until the catalog complains.

How do you phase the build?

Begin with a baseline the business already trusts, such as segment popularity, exposed through the API contract with impression logging in place; this establishes the latency budget, the logging pipeline, and the experimentation harness before any model exists. Add a single learned candidate generator and a simple ranker, and run the first controlled experiment against the baseline. Only after the experiment shows lift add further retrievers, richer ranking features, and business rules, each validated by experiment. Teams that build the full architecture before the first experiment often discover late that their logging cannot support attribution or that the latency budget was never realistic.

What team does the API need?

A product owner who defines the objective and constraints, a data scientist for retrievers and the ranker, a backend engineer for serving and caching, and an analytics partner who owns the experimentation harness and reads results honestly.

How FISTA Solutions builds recommendation APIs

FISTA Solutions builds recommendation APIs to this playbook: product-defined objectives and constraints, feature stores shared across training and serving, multiple candidate generators, bias-corrected rankers, explicit business logic, latency-budgeted serving with fallbacks, online experimentation, and monitoring of relevance, coverage, and fairness. The AI enablement practice delivers the platform, web and mobile integrates the API into product surfaces, and forward deployed engineers embed with your product and data teams. The record behind the work is 150+ projects with 99.9% uptime.

To scope a recommendation API, message FISTA on WhatsApp, or read ai personalization engine for the broader personalization context.