← All posts

Josh Davies

You Can't Redeploy Someone's Phone

Once a mobile app ships, every version of it keeps calling your API until someone taps update. Treat the response shape as a contract, change it by adding, and give yourself a way to say "this version is too old."

  • api
  • laravel
  • php
  • typescript
  • react-native
  • architecture

On the web, you deploy and the next page load gets the new code. Mostly.

Mobile doesn't work like that. You ship a build, it goes through store review, and then people update whenever they feel like it. Some of them never do.

So your API isn't serving "the app." It's serving every version of the app you've ever shipped, all at the same time.

The response is the contract

That app was compiled against a JSON shape. It expects customer_name to be a string. It expects id to be a number. It expects status to be one of four values.

Rename a field, change a type, or make something nullable that never was, and your server tests still pass. The old app shows a blank screen or crashes on launch. Nobody files a bug. They leave a one star review.

The rule is boring on purpose: add, don't change.

  • Add new fields whenever you want.
  • Don't rename. Add the new field, keep the old one.
  • Don't change a field's type.
  • Don't make a field nullable that clients assume is always there.
  • Don't remove anything until you know nobody reads it.

Same goes for anyone else calling your API: partner integrations, a plugin installed on sites you'll never see, a script someone wrote two years ago. If you can't update the caller, you're in the same spot.

Stop returning the model

This is the fastest way to break a mobile app by accident:

public function show(Order $order)
{
    return $order;
}

Now your API contract is your database schema. Add a column, it shows up in the response. Rename one in a migration, you just shipped a breaking change to every phone with your app on it.

Put a Resource in between, so the shape is something you wrote down on purpose:

class OrderResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id' => $this->id,
            'status' => $this->status->value,
            // Kept for app versions before 3.2. Remove when the logs say so.
            'customer_name' => $this->customer->name,
            'customer' => CustomerResource::make($this->customer),
            'placed_at' => $this->created_at->toIso8601String(),
        ];
    }
}

The new app reads customer. The old app keeps reading customer_name. Both are happy, and the comment tells the next person why the duplicate exists.

A new enum value is a breaking change

From the server's side, adding a refunded status feels additive. You didn't remove anything.

The old app disagrees. Its label lookup returns undefined, its switch falls through, and something downstream calls .toUpperCase() on nothing.

You can't fix the versions already out there. You can make sure the version you're about to ship tolerates values it's never seen:

const KNOWN_STATUSES = ["pending", "paid", "shipped", "cancelled"] as const;
type OrderStatus = (typeof KNOWN_STATUSES)[number] | "unknown";
 
export function parseStatus(raw: unknown): OrderStatus {
  return typeof raw === "string" &&
    (KNOWN_STATUSES as readonly string[]).includes(raw)
    ? (raw as OrderStatus)
    : "unknown";
}

Then the UI has one honest fallback for "unknown" (a neutral badge, a generic label) instead of a crash.

If you validate responses with Zod, the same idea applies to fields. z.object() strips keys it doesn't know about by default, which is exactly what you want on a response. Reach for .strict() on a response schema and the day the server adds a field, every installed copy of the app starts rejecting it.

Make the app say who it is

Send the app version on every request:

export async function api(path: string, init: RequestInit = {}) {
  const headers = new Headers(init.headers);
  headers.set("Accept", "application/json");
  headers.set("X-App-Version", APP_VERSION); // from your build config
 
  return fetch(`${API_URL}${path}`, { ...init, headers });
}

Log it on the server. Now you can actually answer "who's still on 3.1?"

That's how you know when it's safe to delete customer_name. Not "it's been a while." It's "nothing older than 3.2 has hit this endpoint in a month."

Keep a minimum version switch

Sooner or later you'll need to stop supporting an old version. Maybe it has a bug that corrupts data, or the field you need to remove is costing real money. You want a lever for that:

class EnsureSupportedAppVersion
{
    public function handle(Request $request, Closure $next): Response
    {
        $version = $request->header('X-App-Version');
        $minimum = config('mobile.minimum_version');
 
        if ($version && version_compare($version, $minimum, '<')) {
            return response()->json([
                'message' => 'This version of the app is no longer supported.',
                'code' => 'app_update_required',
            ], 426);
        }
 
        return $next($request);
    }
}

Requests without the header (the web app, builds from before you added it) pass through. You decide later if that should change.

Here's the part people miss: the app has to know what to do with that response before you ever send it. On app_update_required, show a screen that says "please update" with a link to the store. Ship that handling now, while you don't need it.

A kill switch you add in the version you're trying to kill doesn't kill anything.

Test the shape, not just the status

A test that checks assertOk() will happily pass while you delete half the payload. Pin the fields old clients depend on:

it('keeps the order shape old apps depend on', function () {
    $order = Order::factory()->create();
 
    $this->actingAs($order->user)
        ->getJson("/api/orders/{$order->id}")
        ->assertOk()
        ->assertJsonStructure([
            'data' => [
                'id',
                'status',
                'customer_name',
                'customer' => ['id', 'name'],
                'placed_at',
            ],
        ]);
});

When this test goes red, it isn't being picky. It's telling you someone is about to break the installed base.

The habit

  • Responses go through a Resource, never a raw model.
  • Add fields. Don't rename, retype, or remove them on a whim.
  • Clients ignore fields they don't know and survive enum values they've never seen.
  • Every request carries the app version, and you log it.
  • The "please update" screen ships before you need it.
  • Old fields get deleted when the logs say so, not when you're tired of looking at them.

The web lets you fix a mistake in five minutes. Mobile keeps your mistakes in people's pockets for a year. Build the API like you know that.