App Builder · Ep 8: one API Mesh endpoint, one Cache-Control

Step 1 of 7

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": true in responseConfig.
  • 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-store source makes the whole response no-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": true to responseConfig to turn it on. If you bring your own CDN, set "cache": false instead, so responses aren't cached twice. With the cache off, the answer had no Cache-Status header, but it still carried the source's Cache-Control, which a browser or a CDN in front of the mesh would honour.
  • Expect a few MISS before the first HIT. With the cache on, a repeated query answered MISS, then HIT with Age counting 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 got MISS five times, HIT twice, MISS twice and HIT three times, with Age values that jumped up and down. A HIT on one request says nothing about the next, and a source can see several calls for one query. Read Cache-Status and Age to see what happened.
  • The response is the unit. Query-level caching isn't supported. A response gets one set of Cache-Control headers 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-Control header is read. When they conflict, the mesh picks the lowest value for max-age, s-maxage, stale-while-revalidate, stale-if-error and similar. So a product source at max-age=3600 and a stock source at max-age=60 produce max-age=60. I saw this with max-age, s-maxage and stale-while-revalidate; I didn't try stale-if-error.
  • no-store beats everything. If any source in the response says no-store, the whole response is no-store, whatever the others say. The answer then carries no-store alone, with no Cache-Status, and the mesh asks its sources again on every request. A source that sent private, max-age=300 was never cached either. Commerce's own GraphQL answered no-store on 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-Control set on a source in the mesh config (responseConfig.cache.cacheControl inside that source) applies only when the source sends none. A source that sent max-age=20 or no-store kept its own header next to a default of max-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 to cache. CORS is a browser rule, not access control. A request with any Origin I sent got the configured origin back in Access-Control-Allow-Origin, so a browser blocks the answer, but the query still ran against the sources. The preflight answer also had Access-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 -a for 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 answering HIT with an Age of over two minutes. The purge made the next requests MISS.
{
  "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 private or no-store by nature, and it would turn the whole response uncacheable.
  • Watch out for sources that send no-store by 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. includeHTTPDetails shows 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: null on each simple product and one entry in errors for 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 extensions held the full URL of the reviews API with all the SKUs, and the source's own error text, even with includeHTTPDetails off. 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.

> code for this episodeGitHub · ep8-api-mesh →Agent hand-off →

Written by Vishwas Bhatnagar

Technical Architect. Adobe Commerce, marketplaces and AI-assisted engineering.

More about me →

More