Microservices

Chapter 12 of 27 · Part 6: External API and UI

API gateway and backends for frontends

One entry point for external clients: the API gateway, one backend per frontend, and GraphQL.

key idea / coordinatorservice / good pathin progress / watch outproblem / failureneutral

The problem: chatty clients

A screen often needs data from several services. Calling them all from a phone is slow and fragile.

A mobile app calling services directlyMobile appOrder svcKitchen svcDelivery svcgetOrder()getTicket()getDelivery()plus getBill() from Accountingcombine on phoneFour slow mobile round trips for one screen. The monolith needed one call: getOrderDetails().
Why clients should not call services directlyProblems with direct callsPoor UXmobile latencyComplex appapp does joinsBattery drainevery call costsCouplingslow app releasesProtocolsgRPC, AMQP
Different clients, different needsWeb appsInside firewallfast LAN: direct is OKBrowser JSEasy to updatebut internet latencyMobile appsSlow networksslow store releasesThird partiesNeed stabilityAPI must not break

The API gateway pattern

Put a single entry point in front of the services, like a facade.

The same screen through an API gatewayMobile appAPI gatewayOrder svcKitchen svcgetOrderDetails()getOrder()getTicket()Delivery + Accounting in parallelorderticketone combined replyOne call over the slow mobile network. The fan-out happens on the fast internal network.
What an API gateway doesAPI gatewaysingle entry point (facade)Routingpath to serviceCompositionjoin resultsTranslationREST out, gRPC inClient APIper client typeEdge funcsauth, limits
Edge functionsEdge functionsAuthenticationAuthorizationRate limitingCachingMetrics and request loggingWhere they can liveBackend servicescaching, authorizationSeparate edge servicecentral, one extra hopAPI gatewayfewer hops, simpler

Structure and ownership

Inside, an API layer per client sits on a common layer. Teams can own their own API.

Inside an API gatewayClientsmobile, browser, third partyAPI layerMobile API · Browser API · Public APICommon layerauthentication, logging, metricsServicesOrder, Kitchen, Delivery, ...
BFF patternBackend for Frontendone gateway per clientMobile APImobile team owns itBrowser APIweb team owns itPublic APIAPI team owns itEach client team builds and runs its own API. A shared library gives the common layer.
Benefits and drawbacks of a gatewayBenefitsHides internal servicesClient-specific API, fewer round tripsSimpler client codeDrawbacksAnother highly available part to runCan become a development bottleneck

BFFs in practice

Aggregation and filtering are the gateway's main value. Where it lives decides who can change it.

What an aggregating gateway returnsThe gateway makes the calls, keeps only the fields the screen needs and sends one small reply. It can also batch many ids into one request.Customer svcfull recordOrder svcall order fieldsGatewaykeeps name and the5 latest ordersPhoneone small replyBatching: one request for 10 order ids instead of 10 separate lookups.
Central gateway versus BFFOne shared gateway has unclear owners and becomes a bottleneck. A BFF is single-purpose, owned with its UI.Central aggregating gatewayBackend for frontendWho owns it? Often a silo teamEvery team edits one deployableBloats as each client differsBuilt for one user interfaceOwned by the same team as the UITight coupling to the UI is fineA BFF is like the server half of the user interface.
How many BFFs?One experience, one BFF. REA gave each mobile app its own BFF because separate teams built them. SoundCloud used one for both listener apps.REA: two teams, two BFFsSoundCloud: one mobile teamAndroidiOSAndroid BFFiOS BFFAndroidiOSMobile BFFTeam boundaries decide. SoundCloud staff said they might split theirs.
Extract on the third useTwo BFFs that repeat the same three calls can share a new Wishlist service. Wait for the third use before extracting.Duplicated in each BFFExtracted serviceAndroid BFFiOS BFFCustomerCatalogInventoryAndroid BFFiOS BFFWishlist svcmakes the 3 callsRule of thumb: build the abstraction when you are about to write it a third time.
From Building Microservices: a BFF can also front third parties, such as royalty reporting or set-top boxes. A breaking change for one party then does not hit the others, and you avoid keeping old API versions alive for everyone.

Designing a gateway

It sits on every request, so it must be fast, concurrent and tolerant of failure.

Performance: blocking versus non-blocking I/OSynchronous I/OThread per connectionheavy under loadAsync / non-blocking I/OEvent loopNetty, Spring WebFlux, NodeNetflix's Zuul 2 got about 25% more throughput for I/O-bound work after the switch.
Gateway design issuesDesign issueAnswerPerformance and scalenon-blocking I/OReadable concurrent codereactive: Mono, RxJava, PromisesPartial failurecircuit breaker, cached defaultBeing a good citizenservice discovery, observability

Gateways, service meshes and the perimeter

Two proxy-based tools, two directions of traffic.

North-south and east-west trafficAn API gateway handles traffic entering from outside the perimeter. A service mesh handles calls between services inside it.ClientsAPI gatewaynorth-southInside the perimeterOrder svcPayment svcmesheast-west: service meshone outside call, many inside
Using a gateway well and badlyKeep the gateway generic. When aggregation or protocol rewriting creeps in, business logic ends up in a vendor product.Good usesMisuseReverse proxy to inside servicesAPI keys and rate limitsLogging and usage trackingCall aggregation grows into logicProtocol rewritingRouting internal calls through itNeed aggregation? Use GraphQL or a BFF. If it is a business process, model it as a saga.
API keys, rate limits and usage trackingGateway products grew out of the API economy: keys for third parties, limits and usage tracking for billing.Clientsends API keyAPI gatewayCheck keywho is callingRate limithow oftenTrack usagefor chargingService
Many teams only need a simple reverse proxy for their own web and mobile clients.
How a service mesh worksA proxy runs beside every service, so calls stay local as far as possible. A control plane sets their behavior, such as timeouts and certificates.Control planePod APod BOrder svcLocal proxyLocal proxyPayment svcnetworkThe order service thinks it makes a normal network call.Timeouts, retries, mutual TLS and logging live in the proxy, not in each service.
API gatewayService mesh
TrafficNorth-south: from outsideEast-west: between services
ShapeReverse proxy at the perimeterProxy beside each service, plus control plane
Typical jobsAPI keys, rate limits, routingDiscovery, timeouts, mutual TLS, logging
RuleKeep behavior genericKeep behavior generic
From Building Microservices: a mesh pays off with many services, several languages and Kubernetes. With five microservices it is hard to justify, and switching meshes later is painful. Treat it like choosing a broker or cloud: on the critical path.

Building one

Buy a product for routing, or write code when you need composition.

Implementing a gatewayOff the shelfAWS API Gatewayno compositionAWS ALBbasic routing onlyKong, Traefikyou run it; no compositionBuild your ownNetflix Zuulroutes by path onlySpring Cloud Gatewayroutes + custom handlersComposition needs code, so the book builds one with Spring Cloud Gateway.

GraphQL gateways

Let the client describe exactly the data it wants.

A GraphQL-based gatewayClient queryonly fields it needsGraphQL schematypes + queriesResolversfetch from servicesOne responsenested resultOne flexible API serves very different clients.
Batching and caching in GraphQLWithout batching10 orders → 10 calls to Restaurant svcThe N+1 problemWith DataLoaderLoads in one tick are batched10 orders → 1 batch callCache skips repeat loads

GraphQL in depth

GraphQL was introduced as a gateway option. These are the trade-offs Newman stresses.

A GraphQL query replaces several REST callsWith REST the client gets every field and makes a second call for delivery. A GraphQL query asks for exactly the fields it wants, and resolvers fetch them.RESTGraphQLGET order: every fieldGET delivery: a second callorder(id: 123) { total statusdelivery { company driver duedate } }Resolvers call the right servicesTo add or drop a field, change the query, not the server.New types or fields still need a server change.
GraphQL: strengths and cautionsIt shines at the edge for GUIs and external APIs. Watch query load, caching and writes, and do not treat services as thin database wrappers.Heavy queriesClients shape queries.Hard to throttle.CachingHarder than REST.CDNs help less.WritesFit less well than reads.Many teams use REST.Best at the edge: mobile and GUI clients, and external APIs such as GitHubNot a database API: keep each service's own logic behind the query
From Building Microservices: a GraphQL server can act as a BFF. Keep one per team boundary, because new types still need server changes. Use it at the edge, not for service-to-service calls.

Example: one public gateway

Bootstrapping Microservices shows the same idea on a small cluster: expose as little as possible.

Only the gateway is publicIn the Bootstrapping Microservices video app the customer-facing gateway and an admin gateway are the entry points. Other services live inside the cluster.BrowserFrontend gatewaypublic addressAdmin gatewayseparate entryKubernetes cluster: internal onlyvideo-streamingvideo-uploadhistorymetadatarabbitdb
Private video storage is reachable only through the app, never straight from the internet.
From Bootstrapping Microservices: in the kubectl listing only the gateway service has an external IP. Every other service is a ClusterIP service, visible inside the cluster only.

Recap

Quick check

How does a GraphQL gateway avoid ten calls to Restaurant Service for ten orders?
Show answer

It batches and caches loads with DataLoader, so the ten lookups become one batchFindRestaurants() call.

Why is it risky to do call aggregation inside a vendor API gateway product?
Show answer

You end up baking business processes into a third-party tool you can only configure in its own language, which makes the logic hard to move later. Use GraphQL or a BFF for aggregation, or a saga if it is really a business process.