9 Ways to Improve a Mobile App API

Over our first year in Bangkok, a habit has formed: at dinner we often watch an episode of Gordon Ramsay’s “Kitchen Nightmares.” Ramsay’s rough manner and creative insults lighten the mood after a long workday, even if what he sometimes finds in restaurant kitchens can definitely kill an appetite.

Each episode follows a similar pattern: Gordon tastes the food, talks with owners and staff, and spends an evening watching how the restaurant operates. Then he turns the place upside down: the menu is often overhauled, the dated interior replaced, and—above all—there’s a lot of work on communication and organization among the players.

The high point of every episode is the relaunch: dressed in full chef’s whites, Gordon observes what the team has learned and how they implement his changes. And at that point, you really have to feel for the guy. Sometimes he has to watch as almost nothing improves: dishes go out raw or overcooked, cooks and servers shout at each other, and even the simplest hygiene rules are still being hammered into the kitchen staff’s heads after a week of working together by the British giant himself.

Honestly? What I’ve seen in recent years in the realm of mobile APIs is often alarmingly close to what Gordon Ramsay endures in those moments: as someone who’s accumulated plenty of backend experience and has also spent years in Apple’s ecosystem and with Flutter, it hurts every time to see teams working against each other instead of together. Especially when it comes to integrating a backend API into a mobile app, I often find two camps instead of one unified team.

And although I haven’t started calling people “donut”—which, coming out of my German mouth, would sound only half as funny as with that wonderful British accent—I have at least put together a list of nine real problems I keep seeing in APIs for mobile apps—along with explanations of why they’re real problems and ways to solve them:

1. No Versioning

“Our API doesn’t change.”—Until it does. In many companies, the website is the first client; the mobile app usually follows later. The result is that the API that feeds the mobile app is optimized for the web app, not for the mobile app.

That’s a problem because web apps can be updated just as quickly as backend systems. With a single click, the web app updates along with the backend that serves the API. Every user immediately sees the new version. What was current ten minutes ago has already vanished without a trace.

That’s not how mobile apps work. Smartphone owners decide if and when they update your app. So if your backend updates and the app doesn’t, the app may no longer be able to talk to the backend.

The solution? API versioning—that is, that little “v1” somewhere in the API—usually in the path or in an HTTP header. That ensures the backend can be updated independently—provided that certain changes are equivalent to a new API version (v2, v1.1, …)—specifically those changes your mobile app can’t handle without its own update.

Now you’re probably asking: Which changes can an app handle and which can’t? Perfect segue to the next point.

2. Top-Level Arrays

An example: your app displays a list of recipes delivered by your API. Simple. Your API is probably JSON-based, and your intuition might be to return that list to your mobile app as a plain array.

That’s fine as long as you’re returning 20 recipes. Maybe it’s still fine at 200. But what do you do at 2,000? It may make sense to return the recipes in pages. That requires returning additional information such as the total number of recipes, the current page, and so on.

How do you do that if your API only returns a list? You have to build an object that contains both the list and the additional information. That’s a classic breaking change, and I don’t know a single mobile app that can handle it out of the box.

The fix is dead simple: from the start, always return an object that contains your recipe list as a field. Zalando, for example, recommends this in its API guidelines. Even though this measure is so simple, I keep seeing it ignored.

3. Poor Workflow for Designing New Endpoints

In some companies, backend developers and app folks sit on the same team. In others, the two sides aren’t even in the same ZIP code.

The result? Neither side understands the other. The backend folks see the world through a backend lens. The app folks just want to receive data and display it. No one really has time for the new feature anyway, because ten initiatives need to be finished at once and three people are on parental leave again.

So the API for the new feature gets built whenever there’s time, and requirements and implementations get tossed over the figurative fence like Charlie Harper’s droppings in a plastic bag. (Two and a Half Men? Anyone? No?)

That leads to misunderstandings, feedback loops, frustration in retrospectives, and of course follow-on issues in production.

The solution is pretty simple here too: set aside focused time for new features and talk to each other. Go through the requirements together and design the corresponding endpoints together as well. Agree on paths and data objects that work for both sides, and lock them in (contract). It costs more time, organization, and communication up front, but it saves feedback loops and irritating firefighting sessions in production.

A term to remember: Backends for Frontends.

4. Fields Are Removed from Responses

Speaking of firefighting: by far the most common reason for long evenings at the office and post-mortems in my career is removing fields from API responses. The problem can be summarized in three very short sentences:

“App expects field. Backend removes field. App stops working.”

A small variation is turning a field that has always been present into one that sometimes isn’t. Both are breaking changes (see above). A quick example:

“All customers always have a ZIP code.” Months later, the onboarding flow for new customers changes somewhere in the product, so the ZIP code is no longer required in the first step. Suddenly there are customers without a ZIP code. Accordingly, it’s missing from some customers in the API response. Apps can’t handle that.

The solution? API versioning (see point 1) and close coordination between backend developers and app folks. Some argue that the real solution is to never remove fields or make them optional once they were mandatory and “always there.” In practice, that’s hard and perhaps not helpful over the years if API objects keep getting bigger and eventually no one knows which field is current and which should have been removed years ago.

5. DIY Error Handling

The nice thing about software development is that almost nothing we do is truly new. At GOTO 2024 in Copenhagen, Kevlin Henney made it clear how little innovation happens in programming languages and how much older many concepts are than we think.

That means: whatever you’re building—assume that (almost) all the technical details have already been solved and that there’s a standard for most problems.

Sounds logical, right?

Still, I keep seeing DIY error handling—from internal APIs all the way to large public APIs from well-known providers. If your backend responds with status 200 (OK), no app on earth wants to search the response payload for hints of errors.

Why? A simple reason: the app likely uses standard tooling to connect to the API, e.g., URLSession from Apple’s Foundation. That standard tooling includes standard error handling based on standard error codes from the REST world.

Notice anything? Right: standards (usually) reduce complexity. I’ve often heard, “That doesn’t work for us.” What I’ve heard far less often is a good answer to the repeated question, “Why?”

6. Database-Centric Models

A key principle for every mobile app is: the less logic in the app, the better. Everything the backend can handle should live there. This way, a change in business logic doesn’t have to be rolled out over months before it reaches even the last user (see point 1).

Yet I often see code in apps that exists solely to map models coming from the API into representations suitable for display on the screen. That requires domain knowledge and business logic in the app—and those can change.

The solution, once again, is a backend for the frontend: the models the backend delivers are suitable for the app, even if they differ significantly from their database representation. While that means more mapping logic for different clients lands in the backend, that logic—centralized in one place—is a big win over logic spread across multiple clients (Android, iOS, and web).

7. No Regular Communication

Software stands and falls with communication. A developer who lacks information or doesn’t understand the person across from them can’t work effectively—no matter how good their code or technical understanding is.

Almost all major problems I’ve had to solve in my career arose from insufficient communication. Most solutions I built were only as good as the agreements and designs made beforehand.

These designs don’t have to be shots in the dark: regular exchanges between app and backend folks take time and pack an already-full calendar. But a tighter bond between both “parties” enables more effective collaboration, more mutual understanding and respect, and ultimately better solutions: mobile app APIs become easy to integrate. Backend folks know the app folks’ pain points. Joint rollouts are better coordinated.

Sounds great, right? In my experience, it truly is. It also just makes work more fun.

8. No App Attest / DeviceCheck

Not every app processes sensitive data—an example: my app iana reads users’ Apple Music libraries and generates interactive playlists from them or shuffles by whole albums (just like the old days—who remembers?). The information it processes isn’t personal, and its external communication is minimal.

That applies to only a few apps, though. If your app calls an API developed by your organization, clients other than your app can call it too—for example, attackers who try to extract sensitive data from your backend by pretending to be “your app.”

An easy way to harden such an API is App Attest / DeviceCheck. If anyone knows a request came from a legitimate copy of your app, it’s Apple and Google.

While it’s possible to implement the backend for this mechanism yourself, I advise all my clients to use Firebase App Check: it can be set up very quickly and has the same effect as an in-house implementation.

9. No Force-Update Mechanism

If your app and its API already satisfy the first eight points on this list, you’re well on your way. What remains is residual risk: mistakes happen and are human. Once a faulty app version has been fully rolled out, there’s no way back.

For such cases, a force-update mechanism is absolutely essential: the app version is checked against a minimum version (e.g., provided by your backend), and if the installed version is older, the user sees a prompt to update the app. They have no way to continue using the installed version (hence “force” update).

The problem? A force update only works for versions of your app that already know the mechanism. If you need it for the first time and then add it, it’s too late—unless you’re a Time Lord.

I recommend that every company with its own app add such a mechanism as early as possible: on the one hand, it’s fairly simple to implement. On the other hand, such a mechanism should also have been rolled out for at least a couple of months before you can rely on it and put it to use.

So if your app has no way to force old or faulty versions to update, now is the second-best time to add it—the best time was yesterday.

Summary

Integrating mobile apps with your backend is a more complex task than integrating a web app. Many organizations simply lack the experience—they don’t know what they don’t know. The good news: you’re now well equipped!

None of these nine points is hard to implement. Still, I see every one of these “sins” regularly. Here’s a short checklist with nine questions from the nine points that you and your team can use for orientation:

• Is our API versioned?
• Does our API avoid top-level arrays?
• Do backend and app folks design endpoints together and in sync?
• Are fields in API responses not simply removed or made optional?
• Does our API use standards for error handling?
• Are the response models already prepared for the app?
• Do app and backend folks speak regularly?
• Are we using Firebase App Check?
• Does our app have a working force-update mechanism?

If you can answer all these questions with “Yes,” your mobile app API is better than 90% of all apps I’ve seen so far. If you’ve got open issues, questions, or need support with implementation, get in touch.