Skip to main content

​
Overview

The API configuration controls how the MTB Backend REST API behaves, including pagination limits and response formatting. Configuration is defined in config/api.ts.

​
REST API Settings

The REST API configuration controls default behavior for all API endpoints.

​
Pagination

​
rest.defaultLimit
integer
default:"25"
The default number of items returned per page when no limit is specified in the request.
​
rest.maxLimit
integer
default:"100"
The maximum number of items that can be requested in a single page. Requests exceeding this limit will be capped at this value.
​
rest.withCount
boolean
default:"true"
Whether to include total count metadata in paginated responses. When enabled, responses include the total number of available records.

​
Configuration Details

​
Default Limit

The defaultLimit setting controls how many records are returned when a client doesn’t specify a limit: 
// Client request without limit parameter
GET /api/items

// Response will contain 25 items (default)
{
  "data": [...], // 25 items
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 25,
      "pageCount": 4,
      "total": 87
    }
  }
}
Using a reasonable default limit prevents accidentally returning large datasets and helps maintain API performance.

​
Maximum Limit

The maxLimit setting prevents clients from requesting excessive amounts of data: 
// Client requests 500 items
GET /api/items?pagination[limit]=500

// Response will be capped at 100 items (max limit)
{
  "data": [...], // 100 items (capped)
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 100,
      "pageCount": 1,
      "total": 100
    }
  }
}
Setting maxLimit too high can lead to performance issues and increased server load. Consider your use case carefully when adjusting this value.

​
With Count

The withCount setting determines whether pagination metadata includes the total count: 
{
  "data": [...],
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 25,
      "pageCount": 4,
      "total": 87  // Total count included
    }
  }
}
Disabling withCount can improve performance for large datasets where counting total records is expensive. However, clients won’t know the total number of pages available.

​
Configuration Example

export default {
  rest: {
    defaultLimit: 25,
    maxLimit: 100,
    withCount: true,
  },
};

​
Using Pagination in Requests

Clients can control pagination using query parameters:

​
Basic Pagination

# Get first page with default limit (25)
GET /api/items

# Get first page with custom limit
GET /api/items?pagination[limit]=50

# Get specific page
GET /api/items?pagination[page]=2&pagination[limit]=25

# Get maximum allowed items
GET /api/items?pagination[limit]=100

​
Pagination Parameters

​
pagination[page]
integer
default:"1"
The page number to retrieve (1-indexed)
​
pagination[pageSize]
integer
default:"25"
The number of items per page (capped at maxLimit)
​
pagination[start]
integer
Alternative to page: the index of the first item to return (0-indexed)
​
pagination[limit]
integer
default:"25"
Alternative to pageSize: the number of items to return

​
Response Format

Paginated responses follow a consistent structure: 
{
  "data": [
    {
      "id": 1,
      "attributes": {
        "name": "Item 1",
        "createdAt": "2026-03-01T00:00:00.000Z"
      }
    },
    // ... more items
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 25,
      "pageCount": 4,
      "total": 87
    }
  }
}

​
Best Practices

​
Choosing Default Limit

  • Small datasets: 25-50 items per page
  • Medium datasets: 10-25 items per page
  • Large datasets: 5-10 items per page
  • API responses: Consider mobile data usage and response time

​
Choosing Maximum Limit

  • Public APIs: 100-250 items (prevents abuse)
  • Internal APIs: 500-1000 items (trusted clients)
  • Bulk operations: Consider dedicated export endpoints instead of high limits
Very high limits can cause:
  • Slow response times
  • Increased memory usage
  • Database performance issues
  • Timeout errors

​
Performance Considerations

// For APIs with large datasets
export default {
  rest: {
    defaultLimit: 10,    // Smaller default for faster responses
    maxLimit: 50,        // Lower max to prevent overload
    withCount: false,    // Disable counting for performance
  },
};

​
Common Use Cases

​
Mobile Applications

export default {
  rest: {
    defaultLimit: 20,    // Optimize for mobile data usage
    maxLimit: 50,        // Prevent excessive data transfer
    withCount: true,     // Enable UI pagination controls
  },
};

​
Admin Dashboards

export default {
  rest: {
    defaultLimit: 50,    // Show more data per page
    maxLimit: 200,       // Allow larger views
    withCount: true,     // Display total counts
  },
};

​
Data Export Features

export default {
  rest: {
    defaultLimit: 25,
    maxLimit: 1000,      // High limit for export operations
    withCount: true,
  },
};
For true bulk exports, consider implementing dedicated export endpoints with streaming or background job processing instead of relying on high pagination limits.

​
Troubleshooting

​
Slow API Responses

If your API is slow:
  1. Reduce default and max limits
  2. Disable withCount for large tables
  3. Add database indexes on frequently queried fields
  4. Consider implementing cursor-based pagination for very large datasets

​
Client Receiving Fewer Items Than Requested

The API enforces maxLimit: 
// Request 500 items
GET /api/items?pagination[limit]=500

// Receive only 100 items (maxLimit)
// Check response.meta.pagination.pageSize to see actual limit applied

Build docs developers (and LLMs) love

Get started for freeTalk to us