Pagination

Navigate large result sets with offset-based pagination

The PartsSource APIs use offset-based pagination for list and search endpoints. This provides predictable result ordering and consistent navigation through large datasets.

---

Request Format

Include pagination parameters in the request body for POST search endpoints:

{
  "filters": {
    "email": "[email protected]"
  },
  "pagination": {
    "sortBy": "LastName",
    "sortDir": "Asc",
    "limit": 50,
    "offset": 0
  }
}

---

Pagination Parameters

Parameter	Type	Default	Range	Description
limit	integer	50	1-10,000	Maximum records to return
offset	integer	0	0+	Number of records to skip
sortBy	enum	varies	endpoint-specific	Field to sort by
sortDir	enum	Asc	Asc, Desc	Sort direction

CustomerApi limits: The CustomerApi has a lower maximum limit of 500 records per page to optimize for customer-facing use cases.

---

Response Format

Paginated responses include metadata alongside the results:

{
  "success": true,
  "data": {
    "customers": [
      {"contactId": 1, "firstName": "John", "lastName": "Doe"},
      {"contactId": 2, "firstName": "Jane", "lastName": "Smith"}
    ],
    "pagination": {
      "total": 150,
      "limit": 50,
      "offset": 0,
      "hasMore": true
    }
  },
  "correlationId": "0HN7QJKV3QJ8K:00000001",
  "timestamp": "2025-10-21T14:30:00.000Z"
}

Response Metadata

Field	Type	Description
total	integer	Total records matching the query
limit	integer	Page size used
offset	integer	Records skipped
hasMore	boolean	true if more pages exist

---

Navigating Pages

Example: Fetching All Pages

# First page (records 0-49)
{"pagination": {"limit": 50, "offset": 0}}
# Response: total=150, hasMore=true

# Second page (records 50-99)
{"pagination": {"limit": 50, "offset": 50}}
# Response: total=150, hasMore=true

# Third page (records 100-149)
{"pagination": {"limit": 50, "offset": 100}}
# Response: total=150, hasMore=false

Code Example

public async IAsyncEnumerable<Customer> GetAllCustomers(CustomerSearchFilters filters)
{
    int offset = 0;
    const int pageSize = 100;
    bool hasMore = true;

    while (hasMore)
    {
        var request = new CustomerSearchRequest
        {
            Filters = filters,
            Pagination = new PaginationRequest
            {
                Limit = pageSize,
                Offset = offset,
                SortBy = CustomerSortField.LastName,
                SortDir = SortDirection.Asc
            }
        };

        var response = await _apiClient.SearchCustomers(request);

        foreach (var customer in response.Data.Customers)
        {
            yield return customer;
        }

        hasMore = response.Data.Pagination.HasMore;
        offset += pageSize;
    }
}

---

Sort Fields by Endpoint

Customers / Users

Sort Field	Description
Id	Customer/Contact ID (default)
FirstName	First name alphabetically
LastName	Last name alphabetically
Email	Email address
UserName	Login username

Example:

{
  "filters": {"emailContains": "@hospital.org"},
  "pagination": {
    "sortBy": "LastName",
    "sortDir": "Asc",
    "limit": 25
  }
}

Catalog

Sort Field	Description
PartNumber	OEM part number
Description	Product description
Manufacturer	Manufacturer name
Price	Unit price
QuantityAvailable	Stock availability

Example:

{
  "filters": {"query": "ultrasound probe"},
  "pagination": {
    "sortBy": "Price",
    "sortDir": "Asc",
    "limit": 50
  }
}

---

Validation & Normalization

Invalid pagination values are automatically corrected:

Input	Normalized To	Reason
limit: 50000	limit: 10000	Exceeds maximum
limit: -5	limit: 50	Below minimum (uses default)
offset: -10	offset: 0	Cannot be negative
sortDir: "invalid"	sortDir: "Asc"	Invalid value (uses default)

The API silently normalizes values rather than returning an error. Always check the pagination object in the response to see what values were actually used.

---

Performance Considerations

Large Offsets

For very large result sets, performance may degrade with high offset values:

Offset Range	Performance
0 - 10,000	Excellent
10,000 - 100,000	Good
100,000+	May be slower

Recommendations for large datasets:

1. Use filters to reduce the result set size

2. Use keyset pagination for sequential processing (if supported)

3. Cache results when possible

4. Process incrementally rather than loading all data at once

Efficient Pagination Patterns

// Good: Use filters to reduce result set
var request = new CustomerSearchRequest
{
    Filters = new { status = "active", createdAfter = "2024-01-01" },
    Pagination = new { limit = 100 }
};

// Avoid: Fetching all records with no filters
var request = new CustomerSearchRequest
{
    Pagination = new { limit = 10000 }  // May be slow
};

---

Complete Request Example

cURL

curl -X POST https://api.partssource.com/internal/api/customers/search \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "emailContains": "@hospital.org",
      "lastName": "Smith"
    },
    "pagination": {
      "sortBy": "LastName",
      "sortDir": "Asc",
      "limit": 25,
      "offset": 0
    }
  }'

Response

{
  "success": true,
  "data": {
    "customers": [
      {
        "id": 12345,
        "userName": "asmith",
        "email": "[email protected]",
        "firstName": "Alice",
        "lastName": "Smith",
        "companies": [...]
      },
      {
        "id": 12346,
        "userName": "bsmith",
        "email": "[email protected]",
        "firstName": "Bob",
        "lastName": "Smith",
        "companies": [...]
      }
    ],
    "pagination": {
      "total": 47,
      "limit": 25,
      "offset": 0,
      "hasMore": true
    }
  },
  "correlationId": "0HN7QJKV3QJ8K:00000002",
  "timestamp": "2025-10-21T14:35:00.000Z"
}

---

TypeScript Helper

interface PaginatedResponse<T> {
  data: T[];
  pagination: {
    total: number;
    limit: number;
    offset: number;
    hasMore: boolean;
  };
}

async function* fetchAllPages<T>(
  fetchPage: (offset: number, limit: number) => Promise<PaginatedResponse<T>>,
  pageSize = 100
): AsyncGenerator<T> {
  let offset = 0;
  let hasMore = true;

  while (hasMore) {
    const response = await fetchPage(offset, pageSize);

    for (const item of response.data) {
      yield item;
    }

    hasMore = response.pagination.hasMore;
    offset += pageSize;
  }
}

// Usage
for await (const customer of fetchAllPages(
  (offset, limit) => api.searchCustomers({ pagination: { offset, limit } })
)) {
  console.log(customer.firstName);
}