API gateway versus direct service exposure

01Two public contracts

A mobile home screen needs a profile, recommendations and an unread count. There are two ways to expose those services:

1. Direct endpoints: the mobile client calls the profile, recommendation and count APIs separately. Each service team maintains its own public request fields, responses, errors, access checks and compatibility.
2. Gateway: the client calls one entry point, such as /home. The gateway calls those internal services and returns a documented combined result.

The behavior clients rely on is the API contract. A gateway can keep that contract stable while internal addresses or service boundaries change.

Direct exposure still needs encryption, load balancing, authentication and resource permissions. A gateway does not remove service-side permission checks either. The decision is where public coordination and shared policy are maintained, not whether security exists.

02Centralization has both benefits and costs

Define the combined home response before implementing it:

1. List required and optional data. In this example the profile is required; recommendations and unread count can have explicitly defined partial behavior.
2. The gateway verifies the caller. It sends backend calls in parallel where their work is independent.
3. Give the whole operation one deadline. Each backend receives only its remaining share of time, including time needed to assemble and return the result.
4. Apply the agreed fallback. Omit unavailable recommendations. Use a cached list only if the product specifies its maximum age and the gateway verifies that it belongs to this viewer. Mark an unavailable count as unknown; a failed lookup is not evidence of zero.
5. Return a response whose fields tell the truth. A partial display page must not claim that an unrelated purchase succeeded.

Tools securing service-to-service traffic do not by themselves specify what fields and errors an old mobile client expects.

03Worked example: a mobile home screen

Assume a mobile network round trip adds 80 ms before service work.

1. Three sequential direct calls add about 240 ms of network waiting. That is a possible implementation, not the fairest automatic baseline.
2. Independent direct calls can overlap. Compare their actual longest required path with the gateway path before claiming that aggregation saves 160 ms.
3. Set a 300 ms overall deadline for /home. The gateway requests profile, recommendations and count in parallel.
4. Handle required profile failure. Return the documented failure or an explicitly designed guest state; do not fabricate a signed-in profile.
5. Handle optional recommendation delay. Stop waiting when its allotted time expires. Omit the recommendation field before the overall deadline. A cached list is an alternative only when its age and viewer match the product’s stated reuse rules.
6. Handle count failure honestly. Return unavailable, not a verified zero.
7. Preserve the original deadline. A backend started after 100 ms has at most 200 ms left, including response assembly. It cannot receive a fresh 300 ms timeout while the client is already waiting.

The gateway reduces client coordination and can hide service changes. It also becomes responsible for these partial-failure decisions. Keep state-changing purchases with the purchase service: being able to return half a page does not make half a business transaction acceptable.

04Choose by client and team needs

Choose using clients and operations:

• Direct APIs can fit a few trusted clients, stable service boundaries and teams able to maintain equivalent public controls.
• A gateway can fit many public clients, common policy and slow mobile release cycles. Its stable interface can reduce client updates when internal services move.
• Keep business decisions with their records. The order service decides whether an order may be cancelled. Repeating that rule in the gateway creates a second copy that can disagree.
• Migrate one endpoint at a time. Compare fields, errors, response time and permissions. Preserve a rollback route and support existing clients during a contract change.
• Measure the whole path. Fewer external calls do not remove internal waiting, shared dependencies or gateway failures.

Explain one required result, one optional timeout and the returned fields. That trace shows whether the chosen public boundary actually works.