Flat API ServerSide DataProvider
The CAPIFlatServerDataProvider connects the ServerSide flat logic with the RequestProvider to seamlessly interact with remote server endpoints expecting pagination and sorting queries.
Flat API ServerSide Details
Designed to power Datatables and Lists by automatically pushing route queries to backend API structures.
Extends: Flat ServerSide DataProvider
Uses: RequestProvider
TypeScript
// --- Client Side (Vue) ---
import { CAPIFlatServerDataProvider } from '@katlux/providers/data'
const provider = new CAPIFlatServerDataProvider({
cacheStrategy: 'Memory',
cacheLifetime: 30000
})
await provider.setAPIUrl('/api/v1/users/search')
// Automatically initiates: GET /api/v1/users/search?pageNumber=1&pageSize=10
// --- Server Side (Nuxt Nitro) ---
// server/api/v1/users/search.get.ts
export default defineEventHandler(async (event) => {
const query = getQuery(event)
// The provider automatically sends these 4 parameters as URL query strings:
// pageNumber — number string — current page (e.g. "1"), parse with parseInt
// pageSize — number string — items per page (e.g. "10"), parse with parseInt
// sortList — IDataSort[] serialized as JSON string — deserialize with JSON.parse
// filter — IDataFilter serialized as JSON string — deserialize with JSON.parse
const pageNumber = parseInt(query.pageNumber as string) || 1
const pageSize = parseInt(query.pageSize as string) || 10
const sortList = query.sortList ? JSON.parse(query.sortList as string) : []
const filter = query.filter ? JSON.parse(query.filter as string) : null
// Apply the parameters to your database / ORM layer
const { rows, count } = await fetchDatabaseUsers(pageNumber, pageSize, sortList, filter)
// Return shape must be: { rows: Array<any>, rowCount: number }
return {
rows: rows,
rowCount: count
}
})Constructor Properties (IDataProviderOptions)
Configuration options passed when initializing the API provider.
| Property | Type | Default | Description |
|---|---|---|---|
| pageSize | number | 10 | Number of items to fetch per page (sent to API) |
| currentPage | number | 1 | Initial page number (sent to API) |
| filter | IDataFilter | null | Initial filter (sent as query object to API) |
| sortList | IDataSort[] | [] | Initial sorting (sent as query object to API) |
| SSR | boolean | false | Enables Nuxt useAsyncData integration for SEO and hydration |
| cacheStrategy | ECacheStrategy | null | Strategy for caching API responses via RequestProvider |
| cacheLifetime | number | 0 | TTL for API response cache |
| deduplicate | boolean | true | Prevents duplicate concurrent requests |
| refreshOnMutation | boolean | true | Re-runs refresh automatically on delete |
| urlPageParam | string | '' | URL query parameter key for two-way page synchronization |
Methods & Reactive Properties
Reactive state and methods for controlling the server-side data flow.
| Name | Type | Description |
|---|---|---|
| pageSize | Ref<number> | Current items per page (triggers reload) |
| currentPage | Ref<number> | Current active page (triggers reload) |
| rowCount | Ref<number> | Total records reported by the API |
| loading | Ref<boolean> | API request pending state |
| pageData | Ref<any[]> | Reactive array of the current page's results |
| apiUrl | Ref<string> | Target API endpoint |
| setAPIUrl | (url: string) => Promise<void> | Sets URL and initializes the page handler |
| setPageDataHandler | (handler: TPageDataHandler) => void | Overrides the default HTTP API fetch handler with custom data loading logic. |
| refresh | (hardRefresh?: boolean) => Promise<void> | Re-runs data request. Cache will only be overridden if hardRefresh is true. |
| loadPageData | (opts?: { disableCache? }) => Promise<void> | Triggers a fresh API fetch via useAsyncData |
| setFilter | (filter: IDataFilter | null) => void | Updates filter and resets to page 1 |
| setSortList | (sort: IDataSort[]) => void | Updates sorting and resets to page 1 |
Expected API Parameters
The provider automatically appends these four query parameters to every GET request it makes to your API endpoint. All values are serialized as URL query strings.
TypeScript
// Full URL example:
// GET /api/v1/users/search?pageNumber=2&pageSize=10&sortList=[...]&filter={...}| Parameter | Type (after parsing) | Example value | Description |
|---|---|---|---|
| pageNumber | number | 1 | Current page index, starting at 1. Parse with parseInt. |
| pageSize | number | 10 | Number of records to return for the page. Parse with parseInt. |
| sortList | IDataSort[] (JSON string) | [{"field":"name","direction":"asc"}] | JSON-serialized sort descriptors. Deserialize with JSON.parse. Empty array [] when no sort is applied. |
| filter | IDataFilter (JSON string) | {"active":true} | JSON-serialized filter object. Deserialize with JSON.parse. null when no filter is active. |
TypeScript
// IDataSort shape
interface IDataSort {
field: string // column / field name to sort by
direction: 'asc' | 'desc'
}
// IDataFilter shape
interface IDataFilter {
[key: string]: any // key-value pairs matching your data model fields
}Expected Row Structure
Each row returned by the API must be a plain object. The only hard requirement is a unique identifier field (default: id). All other fields are up to your data model.
TypeScript
// Minimal row — just needs a unique key
{ id: 1, name: 'Alice', role: 'Admin' }
// Server response shape
{
rowCount: 42, // total records (used for pagination)
rows: [ // current page slice
{ id: 1, name: 'Alice', role: 'Admin' },
{ id: 2, name: 'Bob', role: 'User' }
]
}The id field name is configurable via the idKey constructor option.