A headless product page asks Adobe Commerce for the product, a reviews service for ratings, and a stock service for store availability. That's three round trips from the browser, three sets of credentials to keep out of the front end, and three ways to fail. API Mesh for Adobe Developer App Builder puts them behind one GraphQL endpoint, so the page asks one question and the mesh gathers the answers. I ran this mesh on a Stage workspace against a Commerce staging instance. The note at the end says what that proved and what it didn't.
The catch tends to show up in production, and it's caching. A mesh response is cached as one thing, with one lifetime. If one source in a query changes every minute, the whole response is cached for a minute at most, however static the rest of it is. The mesh below is small on purpose; the cache model gets as much room as the mesh. Allow an hour.
TL;DR
- API Mesh puts Commerce GraphQL and other APIs behind one GraphQL endpoint.
- Its cache is off by default. Turn it on with
"cache": trueinresponseConfig. - A response is cached as a whole, with one
Cache-Control. Query-level caching isn't supported. - When sources disagree, the lowest value wins, and one
no-storesource makes the whole responseno-store. - So split queries by how fast the data changes.
You’ll need
- Node.js and the Adobe I/O CLI, logged in (episode 2), with your workspace selected
- Your Commerce GraphQL endpoint
- A REST API to combine. Any JSON API works for practice
- For caching: nothing extra. The mesh has its own cache, off by default. If you already run a CDN such as Fastly in front, you'll use that instead
Install the API Mesh plugin
npm install -g @adobe/aio-cli
aio plugins:install @adobe/aio-cli-plugin-api-mesh
aio console workspace select
A mesh belongs to one workspace, so Stage and Production each get their own.
Describe the sources
A mesh is a JSON file listing each source and its handler. Commerce uses the graphql handler. A REST API without an OpenAPI file uses JsonSchema, spelled exactly like that: jsonSchema is rejected. The other one is openapi.
{
"meshConfig": {
"sources": [
{
"name": "Commerce",
"handler": { "graphql": { "endpoint": "https://shop.example.com/graphql" } }
},
{
"name": "Reviews",
"handler": {
"JsonSchema": {
"baseUrl": "https://reviews.example.com",
"operations": [{
"type": "Query",
"field": "reviewsBySkus",
"path": "/reviews?skus={args.skus}",
"method": "GET",
"argTypeMap": { "skus": { "type": "array", "items": { "type": "string" } } },
"responseSchema": "./reviews-schema.json"
}]
}
}
}
]
}
}
Adobe's docs say source names are letters and numbers only. On my Stage workspace an update with a hyphen or a space in a source name was rejected, and the service accepted an underscore. Stay with letters and numbers anyway.
Join the sources without N+1 calls
Two sources side by side is only half the value. Extend a Commerce product type with an externalReviews field, and tell the mesh how to resolve it. It isn't called reviews because Commerce already has a reviews field on its products, and the mesh build fails on the clash. The example extends SimpleProduct; add the same for any other product type your storefront shows. Use keyField and keysArg, so a category page with 24 products makes one call to the reviews API, not 24.
{
"meshConfig": {
"sources": [ "...as above..." ],
"additionalTypeDefs": "extend type SimpleProduct {\n externalReviews: [Review]\n}\n",
"additionalResolvers": [{
"targetTypeName": "SimpleProduct",
"targetFieldName": "externalReviews",
"sourceName": "Reviews",
"sourceTypeName": "Query",
"sourceFieldName": "reviewsBySkus",
"keyField": "sku",
"keysArg": "skus"
}]
}
}
GraphQL Mesh's batching maps the answers back to products by position, not by sku, so the reviews API has to return one list per SKU, in the order it was asked. I tested what happens when it doesn't. A reversed answer gave 16 of 17 products someone else's reviews, with no error. A list that was one short turned all 17 externalReviews into null with errors. The mesh wrote the SKUs into the query string as skus=A,B, comma separated.
The CLI also limits the name of a file the mesh references. Adobe's docs say a path under 25 characters. What I measured: a file name of 25 characters including .json worked, 26 was rejected by the CLI before anything reached the API, and a longer folder path in front of a short name worked. Hence the short schema name.
The alternative, sourceArgs with {root.sku} and a requiredSelectionSet, works too, but it calls the reviews API once per product. That's the N+1 problem in a new place. With 17 products on my Stage workspace the reviews API got 17 calls instead of one, and the page took a median 3.9 s against 2.8 s over three runs. Those times include my reviews API's State reads and writes and Runtime cold starts, so they show a direction, not the mesh's own speed.
Create the mesh and query it
aio api-mesh:create mesh.json
aio api-mesh:status
aio api-mesh:describe
status tells you when provisioning has finished, and describe prints the endpoint. A build error, such as the reviews clash above, shows up in status, not at create. A build took one to two minutes. Until the first build had succeeded, the endpoint answered that the mesh didn't exist. After a change, aio api-mesh:update mesh.json replaces the configuration. Any time a source's schema changes, update the mesh too, so it picks up the new schema.
Understand how the cache actually works
This is the part worth slowing down for:
- The mesh caches, but only if you ask. Caching is off by default. Add
"cache": truetoresponseConfigto turn it on. If you bring your own CDN, set"cache": falseinstead, so responses aren't cached twice. With the cache off, the answer had noCache-Statusheader, but it still carried the source'sCache-Control, which a browser or a CDN in front of the mesh would honour. - Expect a few
MISSbefore the firstHIT. With the cache on, a repeated query answeredMISS, thenHITwithAgecounting up, and the hit took 35 ms against about 3.8 s for the first answer (my reviews API sat behind it). It doesn't come in a neat order, though. The mesh sits behind several edge caches, and each one fills on its own. Sending one query every few seconds, I gotMISSfive times,HITtwice,MISStwice andHITthree times, withAgevalues that jumped up and down. AHITon one request says nothing about the next, and a source can see several calls for one query. ReadCache-StatusandAgeto see what happened. - The response is the unit. Query-level caching isn't supported. A response gets one set of
Cache-Controlheaders and is cached as a whole. The key is the whole query: a reviews-only query and a reviews-plus-stock query were separate entries. - Sources vote, and the strictest wins. Each source's
Cache-Controlheader is read. When they conflict, the mesh picks the lowest value formax-age,s-maxage,stale-while-revalidate,stale-if-errorand similar. So a product source atmax-age=3600and a stock source atmax-age=60producemax-age=60. I saw this withmax-age,s-maxageandstale-while-revalidate; I didn't trystale-if-error. no-storebeats everything. If any source in the response saysno-store, the whole response isno-store, whatever the others say. The answer then carriesno-storealone, with noCache-Status, and the mesh asks its sources again on every request. A source that sentprivate, max-age=300was never cached either. Commerce's own GraphQL answeredno-storeon my staging, so any query that touches Commerce can't use the mesh cache.- Your mesh config can't override a source. A default
Cache-Controlset on a source in the mesh config (responseConfig.cache.cacheControlinside that source) applies only when the source sends none. A source that sentmax-age=20orno-storekept its own header next to a default ofmax-age=100. To change a source's lifetime, change the source. - A browser calling the mesh directly needs CORS. Set the allowed origins under
responseConfig.CORS, next tocache. CORS is a browser rule, not access control. A request with anyOriginI sent got the configured origin back inAccess-Control-Allow-Origin, so a browser blocks the answer, but the query still ran against the sources. The preflight answer also hadAccess-Control-Allow-Credentials: true, which I hadn't set. - Adobe documents a 2,048-character limit for GET requests. It wasn't enforced for me: GET URLs up to 32,768 characters answered 200. Don't plan around either number. The mesh's own cache accepts GET and POST, and the same query sent both ways looked like two separate entries. A CDN of your own usually caches GET only, so long queries sent as POST bypass it.
- After a mesh change, purge the cache (
aio api-mesh:cache:purge -afor the mesh's own, or your CDN's), or clients keep receiving responses built by the old configuration. An update does not purge: after one, a cached query kept answeringHITwith anAgeof over two minutes. The purge made the next requestsMISS.
{
"meshConfig": {
"responseConfig": {
"cache": true
},
"sources": [ "..." ]
}
}
Design around one response, one lifetime
You can't give the Commerce part of a response one lifetime and the stock part another. If they're in the same query, the shortest one wins. So the design work is in the queries as much as in the mesh:
- Split by volatility. One query for slow-changing data, and a separate request for fast-changing data (stock, price for the customer's group). The first can cache for minutes, the second for seconds or not at all. That only works if every source in the first query sends a cacheable header. On my staging Commerce answered
no-store, so a query with a Commerce field was never cached, and only the reviews-only query was. Check what yours sends before you plan around the mesh cache. - Keep customer-specific data out of cacheable queries. Anything that depends on a customer token is
privateorno-storeby nature, and it would turn the whole response uncacheable. - Watch out for sources that send
no-storeby default. One such source silently disables caching for every query that touches it. Commerce was one for me. Check each source's headers before you add it.includeHTTPDetailsshows them in the answer, along with the caller's IP address and the source's cookies, so turn it off in production. - Behind a CDN, keep cacheable queries short enough for GET. Adobe documents 2,048 characters as the GET limit, which means short field lists and no inline fragments you don't need.
- Warm the cache after a deploy. The first requests after a purge are slow, and because several edge caches fill on their own, one request doesn't warm them all. Run the key queries a few times.
Decide what the page shows when a source fails
Every source is now on the request path, and the mesh is patient. With the reviews source answering after 2, 10, 30 and 55 seconds, the mesh waited each time and returned everything, a few seconds after the source did. I stopped at 55 because Runtime cuts web actions at 60. I also tried to give the reviews source a timeout. A timeout property in its JsonSchema handler was rejected at create ("Unsupported property timeout"), and I found no timeout option in Adobe's handler docs. So put the timeout where you control it: in the source itself, which should answer or fail fast, and in the client that calls the mesh.
Design the page so a null externalReviews still renders the product. A product page that fails because a ratings widget is down is a bug. Here is what a failure looked like:
- A source that answers 500 gives an HTTP 500 from the mesh, but the body still has every product,
externalReviews: nullon each simple product and one entry inerrorsfor each. A client that treats HTTP 500 as "no data" throws away a page it could have shown, so read the body. - A source that answers 200 with invalid JSON gave HTTP 200 and the same body shape.
- The errors leak. Each entry's
extensionsheld the full URL of the reviews API with all the SKUs, and the source's own error text, even withincludeHTTPDetailsoff. Treat those errors as public. - The error answer can still be cached by others. The mesh didn't cache it, but the answer carried the source's
Cache-Control(max-age=300), so a browser or CDN in front could keep the error for five minutes.
Tested on: a real Stage workspace (aio-cli 11.2.0, api-mesh plugin 5.7.2), with a Commerce staging instance and a small reviews API of mine running as a Runtime action. The first build failed on the reviews clash; after the rename it built. The join made one reviews call for 17 products, with the SKUs written as skus=A,B, and maps the results by position. In the cache tests the lowest max-age, s-maxage and stale-while-revalidate won, no-store and private were never cached, a per-source default applied only to a source that sent no header, a purge cleared the entries and an update didn't. I also saw the CORS headers, the error answers and the 55-second wait. The timings include my reviews API's State calls and Runtime cold starts, so they show a direction, not the mesh's own speed. A timeout property on a JsonSchema source was rejected.
Not tested: a timeout on the graphql or openapi handler, how long the mesh waits past 55 seconds, a CDN in front of the mesh, real traffic and hit ratios, a second workspace, stale-if-error, and updating the mesh after a source's schema changes. The tag ep8-api-mesh still has reviews in its mesh file, which fails to build against Commerce; main has externalReviews. The current list is in the repo README.
Done!
Your storefront can ask one endpoint for everything, and you know what its cache can and can't do. Episode 9 gives your app a page in the Commerce admin.
