How do you design APIs for mobile applications?
Who controls the response shape
In REST the server decides the response shape, in GraphQL the client builds it, and in gRPC a compiled contract sets it. The trade-offs come from who decides the shape.
For this question · chapter 1 of 3
Over-fetching and under-fetching
- A profile screen needs its data in one exact shape. The screen has four rows: the name with its avatar, then the last three orders, each with a product name and a total. But the server that answers the request has never seen this screen. Every problem in this concept comes from the server not knowing that shape.
- The first request shows over-fetching: the response is bigger than the screen needs. The call to GET /users/123 returns 24 fields in 2400 bytes, but the screen shows only two of them. The mobile radio still turns on to download the other 22 fields, which the screen never shows. The endpoint is not badly written: it is written once for every caller, and this screen is only one of those callers.
- Under-fetching is the same mistake in the opposite direction. This time the fixed response shape is too small, because the user record holds order_ids, not the orders themselves. So the client has to send a second request. The second request cannot start until the first one has finished.
- On a phone, 610 ms means most of a second of blank screen. The screen waits for a third request to turn the product ids into names. The three requests could not run at the same time, because each request needed ids from the one before it. The three requests also moved 6900 bytes so the screen could show 8 of the 99 fields that came back.
- REST has a reasonable fix: GET /screens/profile, an endpoint that returns exactly the eight fields the profile screen shows. So the profile call takes one trip, 600 bytes and 250 ms. But the order screen and the settings screen each need their own endpoint, so every new screen means a deploy. A ?fields= parameter on the old endpoint does the same job with less setup, but the server still decides which fields exist.
- Speed was never the point, because the purpose-built endpoint was as fast as anything that comes after it. The real question is who decides the response shape. In REST, the server decides the shape, one endpoint at a time. The next two chapters give the other two answers.
A profile screen needs its data in one exact shape. The screen has four rows: the name with its avatar, then the last three orders, each with a product name and a total. But the server that answers the request has never seen this screen. Every problem in this concept comes from the server not knowing that shape.
© LearnThatStack - diagrams may not be republished without permission.
Want a quick review of the fundamentals? See the API Design cheatsheet.
74 of 92 API Design answers are in Pro.
Full answers, code samples, and AI explanations that go simpler or deeper. Cancel anytime.
- Full answers + code
- AI explanations, simpler or deeper
- 1,000 AI credits / month
- Cancel anytime