Pagination

All endpoints that return a list of items support pagination to ensure optimal performance and user experience. This API uses limit/offset pagination, which is one of the most widely used methods that allows you to retrieve large datasets in manageable chunks.

Parameters

limit (optional, default: 10)

Specifies the number of objects to return per page. Must be between 1 and 100.

Example: limit=25

offset (optional, default: 0)

Specifies the number of records to skip before starting to return results. Used to navigate to specific pages.

Example: offset=50 (skips the first 50 records)

page (optional, alternative to offset)

Page number for easier navigation. When provided, the offset is automatically calculated as (page - 1) × limit.

Example: page=3 with limit=10 is equivalent to offset=20

Request Examples

cURL Examples

# Get first 10 items (default)
curl -X GET "https://app.newtrition-data.com/api/v1/search?query=Brot"

# Get 25 items starting from the beginning
curl -X GET "https://app.newtrition-data.com/api/v1/search?query=Brot?limit=25"

# Get page 3 with 10 items per page (items 21-30)
curl -X GET "https://app.newtrition-data.com/api/v1/search?query=Brot?page=3&limit=10"

# Get 15 items starting from the 45th record
curl -X GET "https://app.newtrition-data.com/api/v1/search?query=Brot?limit=15&offset=45"

Response Format

Example Response

{
  "data": [
    {
      "id": "item_123",
      "name": "Example Item"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 20,
    "page": 3,
    "total_count": 150,
    "total_pages": 15,
    "has_next": true,
    "has_previous": true
  },
  "links": {
    "self": "https://app.newtrition-data.com/api/v1/search?query=Brot&page=3&limit=10",
    "first": "https://app.newtrition-data.com/api/v1/search?query=Brot&page=1&limit=10",
    "last": "https://app.newtrition-data.com/api/v1/search?query=Brot&page=15&limit=10",
    "next": "https://app.newtrition-data.com/api/v1/search?query=Brot&page=4&limit=10",
    "previous": "https://app.newtrition-data.com/api/v1/search?query=Brot&page=2&limit=10"
  }
}

Response Fields

data (array)

An array containing the actual response elements for the current page.

pagination (object)

Contains metadata about the current pagination state:

• limit (number): Number of items requested per page
• offset (number): Number of items skipped
• page (number): Current page number
• total_count (number): Total number of items available
• total_pages (number): Total number of pages available
• has_next (boolean): Whether there are more pages after the current one
• has_previous (boolean): Whether there are pages before the current one

links (object)

Pre-constructed URLs for easy navigation:

• self: URL for the current page
• first: URL for the first page
• last: URL for the last page
• next: URL for the next page (null if on last page)
• previous: URL for the previous page (null if on first page)

Search Endpoint Caveat

For GET /api/v1/search and GET /api/v2/search, results are grouped to reduce near-duplicates. Because of that, deep-pagination metadata should be treated as navigation guidance instead of an exact page-count guarantee.

• pagination.total_count may be approximate for deep pages
• pagination.total_pages may be approximate for deep pages
• links.last should not be used to precompute an exact final page for search results

For search clients, prefer sequential navigation with links.next and links.previous. For shallow pagination, the metadata is still useful, but clients should avoid assuming that very deep search pages have exact final-page semantics.

Best Practices

For API Consumers

1. Always specify a limit to ensure consistent results and avoid relying on default values
2. Use the provided links in the response for navigation instead of constructing URLs manually
3. For search endpoints, prefer sequential navigation with next / previous instead of relying on an exact final page
4. Handle edge cases like empty pages or when has_next is false
5. Cache pagination metadata carefully; for search endpoints, deep-page counts are best treated as approximate

Error Handling

When pagination parameters are invalid, the API returns appropriate error responses:

Error Response Example

{
  "code": "INVALID_PAGINATION",
  "message": "Limit must be between 1 and 100",
  "details": {
    "parameter": "limit",
    "provided_value": 150,
    "valid_range": "1-100"
  }
}

Performance Considerations

• Limit size: Larger page sizes reduce the number of requests but increase response time and memory usage
• Deep pagination: Very high offset values may result in slower response times
• Sorting: Paginated results are consistently ordered.

Performance Tip

For optimal performance, keep your page size between 10-50 items and avoid using very high offset values.