Skip to main content
Version: next

Update the Gezy API v4 client

This guide explains how to update the typed API v4 client when the Gezy backend API changes. The client is generated from the OpenAPI specification using Orval, ensuring type safety between Front-Commerce and Gezy.

Overview​

Front-Commerce uses Orval to generate a fully typed TypeScript client from the Gezy API v4 OpenAPI specification. Orval produces one factory per OpenAPI tag (e.g. getMarketplace, getOauth), each accepting an AxiosInstance and returning typed functions for that domain.

This ensures that:

  • TypeScript types always reflect the real API contract
  • Breaking changes are caught at compile time
  • The client is request-scoped (no shared singleton)

The OpenAPI spec is committed in the repository so that CI builds do not depend on a running Gezy backend.

Prerequisites​

  • A running Gezy backend instance with API v4 enabled
  • Node.js and pnpm installed

Updating the client​

Step 1: Fetch the latest OpenAPI specification​

pnpm --filter @front-commerce/gezy fetch-openapi-v4

This downloads the spec from http://localhost:8080/api/v4/openapi.json and saves it to packages/gezy/generated/openapi-v4.json.

To target a different Gezy instance, set the FRONT_COMMERCE_GEZY_ENDPOINT environment variable:

FRONT_COMMERCE_GEZY_ENDPOINT=https://your-instance.lundimatin.biz \
  pnpm --filter @front-commerce/gezy fetch-openapi-v4

Step 2: Regenerate the typed client​

pnpm --filter @front-commerce/gezy generate-api-v4

This runs Orval with the configuration in packages/gezy/orval.config.ts and outputs one module per tag in packages/gezy/generated/api-v4/. Only the tags listed in input.filters.tags are generated.

Step 3: Review the changes​

git diff packages/gezy/generated/

Review the diff to understand what changed in the API. Look for:

  • New or removed endpoints
  • Changed request parameters
  • Changed response shapes
  • Fields that became required or optional

Step 4: Fix compilation errors​

If the API changed in a breaking way, TypeScript will flag errors in the code that uses the generated types. Fix these before committing.

Step 5: Commit both files​

Always commit the OpenAPI spec and the generated client together, so the repository stays consistent:

git add packages/gezy/generated/
git commit -m "chore(gezy): update API v4 OpenAPI spec and generated client"

Using the API v4 client​

The client is accessible through the Gezy DI as publicRestAPIv4, organized by domain:

// In a runtime.ts contextEnhancer
const { marketplace } = services.DI.get("gezy").http.publicRestAPIv4;

// Typed call: params and response are inferred from the OpenAPI spec
const response = await marketplace.getMerchants({ query: "tech", limit: 10 });

For tests, create a client bound to the mock server:

import { getMarketplace } from "@front-commerce/gezy/api-v4/marketplace";

const api = getMarketplace(axios.create({ baseURL: mockServer.url }));
new MerchantLoader(api, makeDataLoaderStub);

Adding a new API tag​

When the backend exposes a new domain (e.g. Disputes):

  1. Add the tag name to input.filters.tags in orval.config.ts
  2. Run pnpm --filter @front-commerce/gezy generate-api-v4
  3. Import the new factory in di.ts and add it to publicRestAPIv4
  4. Add the corresponding export in package.json

Architecture​

Gezy backend
  └─ GET /api/v4/openapi.json
       └─ packages/gezy/generated/openapi-v4.json  (committed spec)
            └─ Orval (orval.config.ts)
                 ├─ input.filters.tags: ["Marketplace", "OAuth"]
                 └─ generated/api-v4/
                      ├─ index.schemas.ts  (shared types)
                      ├─ marketplace/marketplace.ts
                      │    └─ getMarketplace(axiosInstance) → { getMerchants }
                      └─ oauth/oauth.ts
                           └─ getOauth(axiosInstance) → { postToken, getMe }

DI (di.ts)
  └─ publicRestAPIv4:
       ├─ marketplace: getMarketplace(axiosInstance)
       └─ oauth: getOauth(axiosInstance)
            └─ axiosInstance: baseURL + X-LMB-Ecommerce-UUID header

Troubleshooting​

fetch-openapi-v4 fails with a connection error​

The Gezy backend is not running or not reachable. Verify that FRONT_COMMERCE_GEZY_ENDPOINT (or the default http://localhost:8080) is correct and the backend is started.

Generated types do not match the API response​

The committed OpenAPI spec may be outdated. Re-run fetch-openapi-v4 and generate-api-v4 to synchronize.

Orval generates hash-based function names​

The Orval configuration includes a custom operationName function that strips the tag prefix from names (e.g. getMerchants instead of getMarketplaceMerchants). If a new endpoint produces an odd name, adjust the function in packages/gezy/orval.config.ts.