I came across this post on X. (https://x.com/jahirsheikh8/status/2070849696730607695)

Backend Interview Question:
One of these API designs scales much better.
Which one are you choosing?

A)
GET /users/profile
GET /users/settings
GET /users/orders

B)
GET /users?type=profile
GET /users?type=settings
GET /users?type=orders

I figured it was obviously A, but in the replies people were saying "B is far more scalable."

What A advocates mean by scalability

This is scalability as API design.

  • Resources are easy to understand
  • Response types are fixed
  • Easy to write OpenAPI specs
  • Easy to generate SDKs
  • Easy to maintain

For example, looking at

GET /users/profile

you can tell at a glance that it's an API for fetching the Profile.

Even when new features are added,

GET /users/security
GET /users/preferences
GET /users/notifications

can be added naturally.

What B advocates mean by scalability

On the other hand, the original poster seems to have been talking about infrastructure.

For example,

API Gateway
    │
/users?type=profile
    │
Profile Service

/users?type=settings
    │
Settings Service

the idea is that the entry point and interface stay as one, while only the internal services grow.

In other words, they seem to mean "scalable" in the sense that you don't have to add endpoints.

Should infrastructure concerns be brought into API endpoint design?

API stands for Application Programming Interface, an interface for applications to communicate with each other.

Since it is an interface, I believe API design is part of application design and should be considered independently of infrastructure design.

The same thing can be done with

/users/profile
/users/settings
/users/orders

as well.

API Gateway
        │
/users/profile  ─▶ Profile Service
/users/settings ─▶ Settings Service
/users/orders   ─▶ Order Service

In other words, splitting services and scaling out are matters independent of URL design.

It isn't that A can't scale or that B scales because of its URL shape.

Won't a design that grows around B end up as GraphQL anyway?

If you push design B far enough,

GET /users?type=profile

alone stops being enough.

Before long it becomes

GET /users?type=profile,settings

or

GET /users?type=profile&fields=name,email

This is a design where the query parameters specify "what to return."

At that point, it's closer to the thinking behind GraphQL than to REST.

With GraphQL, the client specifies the data it wants, like

query {
  me {
    profile {
      name
    }
    settings {
      theme
    }
  }
}

So the very idea of "switching what gets returned via the query" is leaning toward GraphQL.

Conclusion

The most interesting thing about this discussion wasn't A versus B, but that the two sides meant different things by "scalable."

  • Scalability as API design
  • Scalability as infrastructure configuration

If you mix these two up, the discussion won't line up.

Personally, if you're designing a REST API, I feel A, which clearly separates responsibilities and responses per resource, is more natural.