Another pattern to define product response is:

interface ProductResponse {
 [string]?: number
} & ({
  product: Product
} | {
  products: Product[]
})

Also, we can even think of defining the interface without using union patten and simply define it as:

interface ProductResponse {
  product: Product | Product[],
 [string]?: number
}

But in this way the property name will no more self-explanatory, also it might be difficult to handle the response on application side.

We could define a base response interface and extend it to specific responses like Product, Shipment etc

https://www.typescriptlang.org/docs/handbook/2/objects.html#extending-types

Create a basic POCs for these cases then we will conclude accordingly

Concluded that we will use the pattern of generics.

interface SuccessResponse<Type> {
  list: Type[];
  total: number;
  groups?: number
}

Explored around how success response are returned using rest api from ecoms

In initial exploration found that only the original object/array is returned without any other extra property like total, size, count etc

  // For getting a list of products/orders
  {
    products: [{}, {}]
  }
  
  // For getting a single order/product
  {
    product: {}
  }

In another exploration found that there is no specific key used while returning the response

  // Can be accessible using response.data
  // Getting a list of products/orders
  [{}, {}]
  
  // Get a single product/order
  {}

In one more exploration found that, in case of retriving a single product just return a single object and for retriving a list, multiple other fields with items array is returned

  // Get a single product/order
  {}
  
  // Retriving a list of products/orders
  {
    startIndex: 0,
    pageCount: 0,
    totalCount: 0,
    items: [{}, {}]
  }

One more pattern is identified in which for every api endpoint a separate response type is defined which extends another base response type.
For example when accessing api to get a single product, the response is ProductResponse extends BaseResponse, when accessing api to get a list of products, the response type is ProductListResponse extends OtherBaseResponse`.

Discussed on the above points, and concluded that in case of fetching a specific record like a product/order/shipment using it's id, we will define the return type same as the request resource(product/ shipment / order), and in case when requesting a list of records for a resource we will return an array, total (optional), and groups(optional).

For the case of requesting multiple records:

interface ListResponse<T> {
  list: Array<T>;
  total?: number; // number of records on the server for the specific resource
  groups?: number; // number of groups found when fetching the resource by grouping on a field
}

Explored around the property/variable naming convention used to hold the total and groups value.

In case of solr, ngroups contain the count of the total groups, and matches contain the count of records.

In case of open search, https://opensearch.org/docs/latest/opensearch/bucket-agg/ is similar to grouped logic, and in open search case we get doc_count specifying the number of document in each bucket.

// Response in open search in case of buckets
"aggregations" : {
  "response_codes" : {
    "doc_count_error_upper_bound" : 0,
    "sum_other_doc_count" : 0,
    "buckets" : [
      {
        "key" : "200",
        "doc_count" : 12832
      },
      {
        "key" : "404",
        "doc_count" : 801
      },
      {
        "key" : "503",
        "doc_count" : 441
      }
    ]
  }
 }
}