Ship a SyBazar vendor field without breaking the app

Vendor web, admin, and mobile do not release on the same day. These steps keep a SyBazar REST change from renaming a field out from under a client.

SyBazar vendors publish products from a web app while ops uses a separate admin. Most breakage I have seen was not a missing endpoint. It was a status that used to be a string and became an object.

Step 1: Add fields. Never rename the ones in flight

• New keys are fine. Removing or renaming is a version bump.
• Enums only grow. Deprecated values stay until every SyBazar client is gone.
• Pagination stays items, nextCursor, hasMore — same as Nepmeds list APIs.

Step 2: Return a stable error body

Clients switch on code. Humans read message. Copy this shape in NestJS filters.

export type ApiErrorBody = {
  error: {
    code: string;
    message: string;
  };
};

export const vendorNotApproved: ApiErrorBody = {
  error: {
    code: "VENDOR_NOT_APPROVED",
    message: "This vendor cannot publish products yet.",
  },
};

Step 3: Version only when you reshape

import { Controller, Get, Query } from "@nestjs/common";

@Controller("v1/vendors")
export class VendorController {
  @Get()
  list(@Query("cursor") cursor?: string) {
    return {
      items: [],
      nextCursor: cursor ?? null,
      hasMore: false,
    };
  }
}

Step 4: Add a contract test before merge

Assert the JSON keys on /v1/vendors. If admin and vendor web share this test, a renamed field never reaches SyBazar production.