Wire API Mesh in Front of a Commerce App

Composes Commerce's own GraphQL API and this app's runtime actions into a single mesh schema. Two moves this skill covers: exposing a runtime action as a mesh source, and extending an existing Commerce type with a field resolved by delegating to that source.

This skill assumes general API Mesh knowledge (mesh.json anatomy, handler types, transforms, hooks, secrets, CORS, generic declarative/programmatic resolvers). If any of that is unfamiliar, load it from Adobe's own material first — see References — rather than guessing at syntax. None of that material covers extending an existing Commerce type via additionalResolvers (targetTypeName/sourceTypeName/requiredSelectionSet/sourceSelectionSet) or wrapping an aio-commerce-sdk runtime action as a mesh source — that's what follows.

Prerequisites

• aio plugins install @adobe/aio-cli-plugin-api-mesh is installed.
• If exposing a runtime action as a source, it's already built and deployed with a real, reachable HTTPS endpoint — a source pointing at an undeployed action fails opaquely.
• Check whether a mesh already exists for this workspace: aio api-mesh:get. "No mesh found" → you'll create; otherwise you're editing an existing mesh.json and will update.

Step 1 — Confirm schema shapes via introspection

Before writing additionalTypeDefs or additionalResolvers, introspect the Commerce (or other) GraphQL source you're extending. Don't assume a type/field name from memory or a similar-sounding convention — near-miss names produce a mesh that builds successfully but whose resolver never fires.

curl -s -X POST "<graphql-endpoint>" -H "Content-Type: application/json" \
  -d '{"query":"{ __type(name: \"<TargetType>\") { fields { name } } }"}'

Step 2 — Scaffold sources

{
  "name": "Commerce",
  "handler": {
    "graphql": {
      "endpoint": "<commerce-graphql-endpoint>",
      "operationHeaders": { "Authorization": "{context.headers.authorization}" }
    }
  }
}

Include operationHeaders by default on any source whose schema has customer-, cart-, or session-scoped fields — API Mesh does not forward the caller's Authorization header automatically. Omitting it makes every authenticated query fail with the backend's own generic "not authorized" error, indistinguishable from an invalid token.

To wrap a runtime action, write a small static OpenAPI document describing just its endpoint and reference it by relative path:

{
  "name": "<SourceName>",
  "handler": { "openapi": { "source": "./mesh/<source>.json" } }
}

The OpenAPI document itself needs enough shape for the mesh to generate a Query field from it — not just the pointer above. Minimal example for a single-endpoint runtime action:

{
  "openapi": "3.0.0",
  "info": { "title": "<SourceName>", "version": "1.0.0" },
  "servers": [{ "url": "<runtime-action-base-url>" }],
  "paths": {
    "/<action-path>": {
      "get": {
        "operationId": "<sourceField>",
        "parameters": [
          {
            "name": "<arg>",
            "in": "query",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": { "<resultField>": { "type": "string" } }
                }
              }
            }
          }
        }
      }
    }
  }
}

operationId becomes the Query field name — it must match sourceFieldName in Step 3's resolver exactly, or the resolver builds successfully but never fires.

The declared response schema must match what the action actually returns — the mesh parses according to what you declare, it doesn't reshape data.

Step 3 — Extend a type and wire the resolver

"additionalTypeDefs": "extend type <TargetType> { <newField>: String }",
"additionalResolvers": [
  {
    "targetTypeName": "<TargetType>",
    "targetFieldName": "<newField>",
    "sourceName": "<SourceName>",
    "sourceTypeName": "Query",
    "sourceFieldName": "<sourceField>",
    "requiredSelectionSet": "{ <keyField> }",
    "sourceArgs": { "<arg>": "{root.<keyField>}" },
    "sourceSelectionSet": "{ <resultField> }",
    "result": "<resultField>"
  }
]

Always pair sourceSelectionSet with result when extracting a scalar from an object-returning source field — never use result alone. The result-only path builds its selection set by hand instead of via the GraphQL parser, and breaks with "No type was found for field node ... __typename" specifically when the target field resolves inside a list (e.g. a parent's items[].<newField>). A direct root-query call to the same source field succeeds even when this bug is present, so that test alone isn't sufficient proof the resolver works.

Step 4 — Deploy and verify

If you already know a browser-based app will call this mesh, decide responseConfig.CORS now, before your first deploy — the browser-verification tier below exists to catch a missed CORS config, but deciding upfront avoids a second deploy cycle.

responseConfig.CORS has (at least) two independent dimensions that both need to be right — origin and allowedHeaders — and a correct origin entry says nothing about whether allowedHeaders is complete. Don't decide allowedHeaders by guessing or by copying ["Content-Type", "Authorization"] from an example: read the consuming storefront's own config first and allowlist every custom header sent by whichever GraphQL client(s) actually point at this endpoint, not just the ones a first failed request happens to reveal. In an AEM/EDS storefront built on aem-boilerplate-commerce, header sets are scoped per fetch client in config.json's headers block (e.g. headers.all for the core commerce client, headers.cs for a separate Catalog Service client) — check the scope(s) that correspond to whichever client(s) you're repointing at this mesh, not every scope in the file regardless of relevance. Adding one rejected header at a time from live CORS errors is a multi-round-trip trap — each fix only surfaces the next missing header, and it reads as repeated basic failures to whoever is watching, especially mid-demo.

Before widening allowedHeaders for a header like Store, check whether it's redundant: if the graphql source already hardcodes an equivalent value via operationHeaders (e.g. "Store": "default"), the mesh doesn't need the client to send it at all, and the leaner fix is dropping that header from the storefront's outgoing request config instead of exposing it through CORS. Omitting allowedHeaders entirely is also a valid option in some CORS middleware (headers get reflected from the request instead of allowlisted) — worth checking against the current handler's docs rather than assuming an explicit list is required.

The first aio api-mesh:* call in a session opens an interactive browser login (Waiting for browser login...). An agent without browser access can't complete this itself — hand the printed login URI to the human and wait.

aio api-mesh:create mesh.json -c   # first time
aio api-mesh:update mesh.json -c   # subsequent edits

-c/--autoConfirmAction skips the interactive Are you sure you want to update the mesh: <id>? prompt. That prompt is the only checkpoint before mutating a mesh other people or systems may already depend on — reserve -c for a workspace-scoped mesh you just created yourself (e.g. in CI, or a throwaway dev workspace). When updating an existing, shared, or already-deployed mesh, omit -c and have a human confirm the prompt, or at minimum get explicit human sign-off on the diff before running the command — treat this like any other live-infrastructure change, not a routine CLI call.

Provisioning is asynchronous — poll rather than assume completion:

until aio api-mesh:status 2>&1 | grep -qi success; do sleep 20; done

Verify in two tiers: first the source's root field directly, then the field in its real nested/authenticated shape (a list-nested query with a real caller credential, not a flat root-field call). Tier 1 passing does not prove tier 2 works — the bug above is invisible in tier 1.

If the consuming app will call this mesh directly from a browser (not just server-to-server), add a third tier: a real request from that app's actual origin. The two tiers above only prove server-side reachability — a mesh with no responseConfig.CORS entry for that origin passes both while still failing every browser call through it, not just the new field (see the CORS section of the api-mesh-starter-kit reference below).

Common Issues

• "not authorized" on an authenticated query, even with a valid token — the source's graphql handler is missing operationHeaders. Check mesh.json, not the token.
• "No type was found for field node ... __typename" on a nested/list field, but the source works fine at root — the resolver uses result without sourceSelectionSet. Add it.
• Browser console shows Request header field <X> is not allowed by Access-Control-Allow-Headers in preflight response, but a server-side curl/CLI call to the same mesh works fine — this is a CORS allowedHeaders gap, not a schema/resolver bug; curl and aio api-mesh:status skip the browser preflight entirely, so they can't catch it. Read the storefront's own config for the full header set sent by whichever client is calling this endpoint (see Step 4), fix allowedHeaders for all of them at once, and check first whether the header is redundant before just appending it to the list.

Quality Bar

• aio api-mesh:status reports success, and the new field resolves correctly in its real nested/authenticated shape, not just at the source's root field.
• If a browser-based app will call this mesh, that app can complete a real request against it — not just aio api-mesh:status and curl.

Chaining

• The source doesn't exist yet as a runtime action — invoke commerce-app-storage, commerce-app-webhooks, or commerce-app-eventing to scaffold and deploy it first.

References

• API Mesh prompting guide — Adobe's own guidance for prompting an agent to write mesh configs; general workflow and expectations
• api-mesh-starter-kit llm.txt — reference knowledge base covering mesh.json anatomy, all three handler types, transforms, hooks, secrets, context state, CORS, and the CLI command set