Serving Both Plain Rork and Rork Max From One Backend — Designing an API Response Contract That Never Breaks Old Binaries

Clients "drop what they don't know"

The parsing side on both runtimes is built to silently discard unknown fields the server might add later. As long as this holds, the server stops fearing additions.

The React Native side (plain Rork) pulls out only the fields it needs and fills gaps with defaults.

// Parsing on the plain Rork (React Native) side
type Wallpaper = { id: string; title: string; isPremium: boolean };
 
async function fetchWallpapers(): Promise<Wallpaper[]> {
  const res = await fetch(`${API_BASE}/wallpapers`, {
    headers: { "X-Client-Version": String(CLIENT_VERSION) },
  });
  const env = await res.json();
  if (env.error) throw new Error(env.error.code);
  // never touch unknown keys; take only what you need, with defaults
  return (env.data.items ?? []).map((it: any) => ({
    id: String(it.id),
    title: it.title ?? "(untitled)",
    isPremium: Boolean(it.isPremium ?? false),
  }));
}

The Rork Max (native Swift) side follows the same thinking. Swift's Codable automatically ignores keys not declared on the struct. Fields that might be absent are treated as Optional, or given a default after decoding.

// Parsing on the Rork Max (native Swift) side
struct Envelope<T: Decodable>: Decodable {
    let data: T
    let meta: Meta
    struct Meta: Decodable { let minSupported: Int }
}
 
struct Wallpaper: Decodable {
    let id: String
    let title: String?        // Optional, in case it ever goes missing
    let isPremium: Bool?
    var displayTitle: String { title ?? "(untitled)" }
}
 
struct WallpaperPage: Decodable { let items: [Wallpaper] }

What both share is a posture: not "mirror everything the server sent exactly," but "extract only what I need, resiliently against absence." That alone makes server-side additions invisible to the client.

Capability flags absorb "features only one side has"

Plain Rork and Rork Max can do different things on the device. Live Activities and some widget surfaces, for instance, only exist natively. If the server starts writing if (platform === "ios-native"), those conditionals multiply with every new client.

Instead, the client declares what it can do, and the server adds data according to those capabilities. The trick is to hand the decision to the client side.

// the client declares its own capabilities
// X-Capabilities: liveActivity,widgetLarge,offlineQueue
const caps = new Set((req.headers.get("X-Capabilities") ?? "").split(","));
 
const payload: any = { items };
if (caps.has("liveActivity")) {
  payload.liveActivityToken = await issueLiveActivityToken(userId);
}
return ok(payload, /* minSupported */ 3);

Now a plain Rork client without that capability simply does not receive liveActivityToken, and thanks to the "drop what you don't know" rule above, nothing breaks. When a new capability appears, you add one flag. Not branching on platform names is what keeps you out of conditional hell over the long run.

The changes you must not make

"Additive only" is easy to say, but in practice changes show up where you genuinely wonder, "is this additive or breaking?" Here is the table I use to decide.

When you want to rename, the standard move is to keep the old name and add the new one. My own failure at the top would have been a non-event if I had merely "added" displayTitle without removing title. Return both for a while, and only fold the old name away once the clients reading it have shrunk far enough.

Separately from these contract questions, you should settle which keys may live in the client and which never can, ahead of time. That call is covered in "Why hardcoding an API key in a Rork (Expo) app gets it stolen, and how to design the proxy," which is worth getting in order alongside this.

When to retire an old contract — decide from the logs

Grow additively for long enough and eventually you will want to fold away an "old shape nobody uses anymore." Lean on a hunch here and you cut off devices still using it. Make the call from real data pulled from logs, not from guesswork.

Stream the X-Client-Version that rides on every request into your Workers aggregation. On Cloudflare, writing to Analytics Engine is the easy path.

// measure the version distribution (the basis for retirement decisions)
env.VERSIONS.writeDataPoint({
  blobs: [req.headers.get("X-Client-Version") ?? "unknown"],
  indexes: ["client_version"],
});

The thresholds I use as a guide for retiring an old contract are these.

Even then, do not delete in one stroke. First raise meta.minSupported so the affected clients show an update banner; only once the remaining devices drop below the threshold do you remove the old server-side branch. Separating the step that raises minSupported from the step that deletes the code is the only way to stay able to roll back.

Make it a habit, not a one-time design

The real value of this design, I have come to feel, is not in any flashy feature but in how it turns into a habit of pausing for a beat before you deploy. Once you hold the three shapes — envelope, additive-only, capability flags — you naturally re-ask, with every change, "does this break an old binary?"

The more the pragmatic split spreads — build fast in plain Rork, add Rork Max where native is required — the more often a single backend supports several runtimes at once. What pays off then is not the count of features but the discipline of not breaking the contract.

As a next step, re-wrap even one existing endpoint in the envelope shape and wire up X-Client-Version aggregation. The foundation that lets you decide when to retire is the very first thing you will gain. Thank you for reading to the end.