Pragmatic Backend APIs For Mobile Apps
The best mobile apps are optimized, from the client to the backend API. There are different approaches for the API: REST, RPC, GraphQL, etc. None are the silver bullet. You have to make your own blend
Over the years of mobile development, I’ve seen all sorts of API implementations—from crudely assembled XML and JSON endpoints all the way to strict REST and OpenAPI contracts.
What’s interesting is that, quite often, not only the backend engineers designing the APIs do not fully understand the constraints and best practices for mobile, but even mobile engineers themselves don’t know what a good backend API for mobile should look like.
In this article, I’ll outline my high-level approach and what I care about when designing backend APIs for mobile apps.
The Problem. Typical Approach. Abdication of Responsibility.
When I ask mobile developers what makes a good API, they typically give me vague answers like, “It should be JSON, it should be RESTful, and it should be optimized for mobile and scale well.” Sometimes I even hear “it all should be GraphQL!”
At the end of the day the tendency of mobile engineers is to just blindly accept the API that they are given or rely on the backend engineers to create something decent that would be convenient and effective for the mobile app to consume.
Mobile engineers should either advocate for and educate backend developers about effective mobile-first API design, or ideally, take the lead by designing the API contract themselves for the backend team to implement.
Mobile App Constraints
Mobile apps run on mobile devices (duh!). Despite advancements in chip design and battery life they are still much more limited than an application on the desktop that has persistent internet and power connection.
Connectivity: Networks are spotty, slow, and often intermittent (e.g., commuting in a subway).
Battery: Every network request and CPU cycle drains the battery.
Memory: Limited RAM (I mean relatively speaking nowadays) means working large data sets is still a challenge on mobile
System Optimization: because of all of these challenges there are system optimizations in place where the work/compute of your app can be paused and resumed or limited by the OS itself.
API Versioning is important: mobile apps do not update on users devices in a blink of an eye/page refresh like the web apps do so maintaining several versions behind of your API is prudent to keep older versions of the app still working.
Because of all of these constraints it usually leads to issues and degraded user experience if you reuse the same backend APIs that power, let’s say, your web/desktop application, and use them in your mobile application.
Typically reusing the API like this leads to mobile apps stitching several API requests of poorly optimized bloated JSON together to give something meaningful to the user like a complete feature or full screen of data for a given user experience.
Pragmatic JSON API Design for Mobile
There are several different approaches, architectures, design patterns, and conventions out there on how to organize and assemble your backend APIs. Here are some of the most common ones you would encounter:
REST vs GraphQL vs RPC
The debate around API design often revolves around what architectural style to pick for the API. Is it GraphQL that’s the best? Or REST? Or RPC? Or something else?
At the end of the day they have their own pros and cons. I am not going to dive deep into them here but here’s my brief take.
GraphQL. the best for public APIs. poor choice for internal API.
GraphQL - sounds good in theory but in practice a poor choice for API design for an internal API for your own mobile app consumption. The abundance of choice and permutations and configurability of the “queries” from the client side put the burden of API design on the client rather than where it belongs on the blacked. This leaves backend with highly unpredictable and hard to optimize mess of requests/queries that is difficult to support and scale.
GraphQL is better reserved for situations where you don’t know the use case for your API upfront - aka for publicly facing APIs, because you don’t know how your users will be actually getting and sending the data to your backend and what is actually important to them, so yuo optimize for abundance of choice rather than on specific pre-determined/prescribed set of actions/choices/user flows.
RPC. problem domain specific but not standardized.
RPC is where the API organized around “remote procedure calls” (hence the name) and the idea behind it is that you make a call on the client side like it was “yet another method call for yet another procedure of your app” but under the hood, instead of executing it locally, it calls a “remote server” to do the compute and then it returns the result asynchronously. It’s a convoluted way of describing an API where it doesn’t have strict standardization and rules and has a much more free form arrangement/implementation where the endpoints you call mimic potential method calls if you were to call them locally rather than on the backend server.
The upside of this design pattern for API is that you could be very specific with the domain problem you’re solving and the API you’re serving for mobile but the downside is that there is no standard and it could lead to a bit of a chaos with widely different implementations even on the same backend API server. REST has a much better story on standardizing how the API endpoints look and behave.
REST. the golden standard. Solid overall choice.
REST is a fantastic standard and API design/architecture that nowadays is a golden standard and the golden foundational best practice for designing your own APIs. It encompases everything from the low level stuff like using HTTP status codes and verbs properly and extensively all the way to the high level prescription of organizing your endpoints around resources/entities in your system.
REST is probably the best choice if you don’t know what you’re optimizing for yet and just need to get started. It will carry you forward far, sometimes very far, but the downside is that you can’t always model everything around resources, especially when it comes to rich user experiences on mobile where one single screen might do a lot of stuff for the user. You will find yourself stitching multiple REST endpoint requests to multiple resources/endponits quite fast as you try to fulfill the data requirements for your mobile application screens.
Bespoke Backend APIs for Mobile User Experience (a little bit of RPC, a little bit of REST)
So what does “API optimized for mobile” even mean? Afterall we have all these choices (and more that I haven’t covered) to design our backend APIs consumed by mobile apps. Which one to go for?
At the end of the day I came to a conclusion that there is no one best option to go with and instead a highly optimized backend API for mobile should contain in itself the best parts of every approach.
Basically it boils down to - the API mobile app consumes needs to be bespoke and highly optimized for the user experience this API supports.
RPC style user experience endpoints
In practice this means that instead of RESTful collection of resources API style where the mobile app needs to make multiple requests and stitch data together on the client side to serve a screen or a feature you instead would create an RPC style API where each endpoint returns full set of data needed for a given screen or feature to work.
Highly optimized mobile endpoints like that would receive and return only the data needed for the mobile app to function, no more no less. They would not have any extra fields, properties, data, etc. “just in case” or because the endpoint is shared with other clients such a desktop web app. It wastes resource if you do it this way.
There would be no generic /users/235 or /posts/123 and /posts/123/comments endpoints. Instead you get one RPC style endpoint such as /postDetails/123 that returns combined, and only necessary, fields from all 3 of those endpoints to serve a post details screen in a mobile app that displays some post info + the comments + some of the author user info.
HTTP status codes and verbs
Highly optimized mobile endpoints, unlike simple RPC ones, utilize HTTP status codes and HTTP verbs heavily, just like REST endpoints do. The reason is because the convention is highly understood and predictable and conveys a lot of information about the request or response in a very short and concise manner. This makes the API instantly recognizable and predictable in its behavior. You can even get a lot of code generation/automation with popular networking libraries out there “for free” out of the box if you stick with these conventions.
API Versioning
Highly optimized mobile endpoints are heavily versioned. As mentioned above, mobile apps do not update all at once and there are always laggard users who update their applications late or refuse to do so. Highly optimized mobile endpoints need to be versioned to support those older versions of the app that are still in users hands despite the new hot latest app update that you pushed to the app store.
There are different ways and approaches to versioning backend APIs and it could be an entire article on its own to explore all of them. I’ll just leave it here by sharing what worked for me - version endpoint by endpoint and version frequently. Rely on passing IDs/UDIDs of your entities as much as possible instead of full object shapes, it helps with backwards compatibility of your domain models.
Conclusion
Even though we, as mobile engineers, might not care as much about backend API design, it is actually very important for us to be not only aware but advocate for more highly optimized mobile API endpoints to make our apps better, our user’s experience better, and our coding lives easier.
Go talk to your backend engineers about this. It’s 2025, there is no excuse to keep accepting the backend API you’re given stitching together 10 different endpoint responses on the client side to simply display a screen in your mobile application.