「对内优化『改得快』、对外优化『不破坏』」——同一份数据,UI 用 tRPC、SDK 用版本化 REST。你做过或用过的系统里,内部接口和对外 API 是怎么处理这对矛盾的?如果让你给一个对外 API 设计「演进而不破坏」的机制,你会怎么做版本、怎么防契约漂移?
Lesson 21 opened the "staff entrance" for the in-house UI (tRPC). This lesson opens the third and last door — the public REST API for
external SDKs. Its priorities differ sharply from tRPC's: internally seek type-safety, fast to change; externally seek contract stability,
holding up at scale. Four things to see: how a route factory unifies auth/rate-limit/validation across all endpoints, how auth uses a
Redis cache to withstand massive traffic, how versions are managed by folder, and how a Fern contract generates multi-language
SDKs. Finish this and Lesson 20's "three doors" are all open.
🏛️ Analogy
Think of the public REST API as a government building's public service hall. Whatever business you come for (query a trace, submit a score, pull a
dataset), you first go through the same security and queue process (the route factory: check ID, rate-limit, verify your form is filled right) — no
one skips it. Frequent visitors get their ID info cached at the front desk, no trip to the archives each time (Redis-cached auth). The hall's
procedures are printed into a manual and translated into your language (Fern generates multi-language SDKs); when procedures update, the old
manual still works, the new procedure ships as "v2", existing users unaffected (versioning by folder). Unified, stable, cacheable, versioned —
that's what an external API should look like.
One route factory, unifying every endpoint
Just as tRPC converges auth into procedure builders (Lesson 21), the public REST converges every endpoint's "mandatory moves" into one route factorycreateAuthedProjectAPIRoute. Each endpoint just declares its query/body/response schema and rate-limit resource, and the factory uniformly
runs these gates:
The unified pipeline for external endpoints: createAuthedProjectAPIRoute runs auth (key→project, incl. access level) → rate limit → Zod-validate query/body → the handler in an OTel context (surface=publicapi) → validate the response (dev, anti contract-drift); oversized body → PayloadTooLargeError. Source: web/src/features/public-api/server/createAuthedProjectAPIRoute.ts.
The same domain objects, exposed (endpoint per web/src/pages/api/public/traces; values illustrative): Basic-auth with pk:sk and GET /api/public/traces/{{id}} returns a JSON — the same trace you see in the UI: observations[], scores[], totalCost, latency. Fern generates multi-language SDKs from the API definition, so REST and every client get the same shape.
// each endpoint only declares schema & rate-limit resource; the factory runs auth/limit/validate/OTelexport const handler = createAuthedProjectAPIRoute({
name: "Get Traces",
querySchema: GetTracesV1Query, bodySchema: z.never(),
responseSchema: GetTracesV1Response,
rateLimitResource: "public-api",
allowedAccessLevels: ["project"], // this endpoint needs a project-level key
fn: async ({ query, auth }) => { /* business only: already authed + validated */ },
});
This is Lesson 21's "security by structure" on the REST side: auth, rate-limit, Zod validation don't rely on each endpoint author's diligence — the
factory forces them all. The difference is priority — tRPC's set is internal; REST's adds rate limiting (against external abuse), response
validation (against external contract drift), access levels (e.g. Bearer read-only scores) — gates only the public-facing side
needs.
An external API verifies a key on every request — and an SDK may send thousands per second. Hit Postgres for every key check and the database gets crushed by
auth itself. So ApiAuthService wraps key verification in a Redis cache:
Cache the positives, and the negatives too: auth checks Redis first, returns on hit; on miss falls back to Postgres by fastHashedSecretKey and re-caches. The key is negative caching: even "this key doesn't exist" is recorded (API_KEY_NON_EXISTENT), so attackers brute-forcing with fake keys can't pound the database. Source: web/src/features/public-api/server/apiAuth.ts:75.
😖 no cache: every request hits the DB
The SDK sends tens of thousands of requests a second, each verifying a key against Postgres — a big chunk of the DB's load is auth itself, slowing things before business even starts; attackers flooding with fake keys hit the DB directly.
😀 cache + negative cache: the DB is barely touched
Common keys hit Redis, key checks near-zero-cost; even "nonexistent keys" are stopped at the Redis layer by negative caching. Whether normal traffic or malicious flooding, Postgres is shielded behind, disturbed only on a cache miss.
Versions by folder, contracts by Fern
An external API, once published, can't change freely — but needs keep evolving, so what? Langfuse's two moves: version by folder, generate SDKs
with Fern.
version = folderv1 at root, v2/, v3/…
v1 sits at the public/ root by default, new versions in v2/, v3/ subfolders. Old paths never change, so your two-year-old integration still runs today; opt into new capability by explicitly switching version.
new versions can subtractdrop expensive features
A new version isn't only additive; it can cut costly old designs: e.g. v3/scores drops the userId/traceTags filters that need a trace JOIN and uses cursor pagination — writing "use v2 for that" straight into the docs.
Fern contractone YAML → multi-language SDKs
The API contract is hand-written Fern YAML (fern/apis/{server,client}/…), which generates the Python and TypeScript SDKs (generated/) and exports OpenAPI. Define once, consistent everywhere.
Together these are Lesson 20's "externally seek contract stability" made real: versioning ensures "the old doesn't break", Fern
generation ensures "multi-language consistency, contract-as-docs". Paired with dev-time response-schema validation (against the hand-written implementation
silently drifting from the Fern contract), the whole external channel stays stable and never quietly changes shape.
🎯 Design trade-off
It's all "query the data out", so why does the UI use tRPC while the SDK needs this whole REST factory + cache + versions + Fern? Because
different audiences, different constraints (echoing Lesson 20). The UI is in-house, same repo, so tRPC trades type threading for iteration
speed, where daily changes are fine. The SDK faces external, massive, long-lived users: massive, so auth must be cacheable (Redis +
negative cache), or the DB gets crushed by key checks; long-lived, so the API must be versioned (folders + Fern), or one change breaks someone's
two-year-old integration. The same "converge cross-cutting concerns into one factory" pattern (Lessons 21, 22) takes on a public-facing new meaning
here: rate-limit against abuse, response-validate against drift, cache to take traffic, version to stay stable. Internally optimize "fast to change",
externally optimize "don't break" — the same data, two engineering value systems parting ways. With that, Lesson 20's "three doors" are all walked through:
tRPC for the UI, REST for the SDK, App-Router for streaming/webhooks — each divided and conquered by audience.
🎯 Key points · Part 4 wrap-up
One route factorycreateAuthedProjectAPIRoute unifies every public endpoint's auth → access level → rate limit → Zod-validate query/body → OTel(surface=publicapi) → response validation → oversized-body rejection.
Auth uses a Redis cache to scale: hit returns directly, miss falls back to Postgres by fastHashedSecretKey and re-caches; negative caching (API_KEY_NON_EXISTENT) blocks fake-key brute force.
Versioning by folder: v1 at root, v2/v3 subfolders; old paths never change, new versions can subtract (e.g. v3 scores drops JOIN-needing filters, uses cursor pagination).
Contract by Fern: hand-written Fern YAML → generated Python/TS SDKs + OpenAPI; dev-time response validation guards against the implementation drifting from the contract.
Tradeoff: internal (tRPC) optimizes type-safety and speed, external (REST) optimizes stability and scale — same data, two value systems. With this, Lesson 20's "three doors" are all open.
🧪 Self-test - think about the design
1. The public REST API unifies all endpoints with one route factory createAuthedProjectAPIRoute. Compared to Lesson 21's tRPC procedure builders, what 'public-facing' gates does it add?
faster database connections
it removes auth
rate limiting (against external abuse), response validation (against external contract drift), access levels (e.g. Bearer read-only scores) — gates the internal tRPC doesn't need but the external API must have
more complex type checking
Show answer & explanation click to expand
Answer: C. Both use the same 'factory/builder converges cross-cutting concerns' pattern, but with different priorities: tRPC seeks internal speed, REST external stability and scale, hence the added rate-limit, response validation, access levels. Auth and Zod validation are common to both — neither relies on endpoint-author diligence; the factory forces them.
2. An external API verifies a key per request, and SDKs may send tens of thousands per second. Besides caching valid keys in Redis, Langfuse deliberately 'negatively caches' nonexistent keys. What does negative caching prevent?
prevents version mismatch
brute-forcing the DB: attackers flood with many fake keys; without caching 'nonexistent', each fake key would hit Postgres; negative caching (API_KEY_NON_EXISTENT) blocks them at Redis from the 2nd hit, shielding the database
prevents oversized responses
prevents key leakage
Show answer & explanation click to expand
Answer: B. Caching only valid keys still lets attackers with floods of nonexistent keys punch through to Postgres each time. Negative caching records 'this key doesn't exist' in Redis too, so whether normal traffic or malicious flooding, the DB stays shielded behind the cache, disturbed only on a true miss. A 'cache the positives and the negatives' security consideration.
3. Langfuse manages the external API with 'versioning by folder' (v1 at root, v2/, v3/) + 'Fern contract generates SDKs'. What core tension does this combo resolve?
the tension between 'needs evolve' and 'can't break existing users after release': folder versions keep old paths unchanged (old integrations run) while new versions opt-in and can even subtract; Fern's one contract generates multi-language SDKs ensuring consistency, with dev-time response validation against drift
makes API responses faster
reduces the number of endpoints
lets the frontend skip code
Show answer & explanation click to expand
Answer: A. An external contract can't change freely once published, yet needs keep evolving. Folder versions keep v1 unbroken and put new capability in v2/v3 (even cutting costly old designs, e.g. v3 scores dropping JOIN-needing filters for cursor pagination); Fern generates Python/TS SDKs + OpenAPI from one hand-written YAML, define-once consistent everywhere. This realizes Lesson 20's 'externally seek contract stability'.
💭 Open questions (no single right answer - just think or try)
'Internally optimize fast-to-change, externally optimize don't-break' — same data, UI via tRPC, SDK via versioned REST. In systems you've built or used, how were internal interfaces and external APIs handled against this tension? Designing an 'evolve without breaking' mechanism for an external API, how would you do versioning and prevent contract drift?