Data Fetching

Learn how to fetch, filter, and paginate data from our API.

Basic Data Fetching

Our SDK provides simple methods to fetch data from our API. Here are the basic patterns:

import { Client } from '@acme/sdk';

// Initialize the client
const client = new Client({
  apiKey: 'YOUR_API_KEY',
});

// Fetch all items
async function getAllItems() {
  const items = await client.items.list();
  console.log(items);
  return items;
}

// Fetch a specific item by ID
async function getItem(id) {
  const item = await client.items.get(id);
  console.log(item);
  return item;
}

// Execute the functions
getAllItems();
getItem('item-123');

javascript

Filtering and Sorting

You can filter and sort data to retrieve exactly what you need:

import { Client } from '@acme/sdk';

const client = new Client({
  apiKey: 'YOUR_API_KEY',
});

// Filtering examples
async function filterItems() {
  // Filter by a single property
  const activeItems = await client.items.list({
    filter: {
      status: 'active',
    },
  });
  
  // Filter by multiple properties
  const recentActiveItems = await client.items.list({
    filter: {
      status: 'active',
      createdAfter: '2023-01-01',
    },
  });
  
  // Filter with operators
  const expensiveItems = await client.items.list({
    filter: {
      price: { gt: 100 },
    },
  });
  
  return {
    activeItems,
    recentActiveItems,
    expensiveItems,
  };
}

// Sorting examples
async function sortItems() {
  // Sort by a single property (ascending)
  const itemsByName = await client.items.list({
    sort: 'name',
  });
  
  // Sort by a single property (descending)
  const itemsByPriceDesc = await client.items.list({
    sort: '-price',
  });
  
  // Sort by multiple properties
  const sortedItems = await client.items.list({
    sort: ['category', '-createdAt'],
  });
  
  return {
    itemsByName,
    itemsByPriceDesc,
    sortedItems,
  };
}

javascript

Available Operators

Our filtering system supports the following operators:

eq: Equal to (default when no operator is specified)
ne: Not equal to
gt: Greater than
gte: Greater than or equal to
lt: Less than
lte: Less than or equal to
in: In a list of values
nin: Not in a list of values

Pagination

When dealing with large datasets, pagination is essential for performance:

import { Client } from '@acme/sdk';

const client = new Client({
  apiKey: 'YOUR_API_KEY',
});

// Basic pagination
async function paginateItems() {
  // Get the first page with 10 items per page
  const firstPage = await client.items.list({
    page: 1,
    limit: 10,
  });
  
  console.log('First page items:', firstPage.data);
  console.log('Pagination info:', firstPage.meta);
  
  // Get the second page
  const secondPage = await client.items.list({
    page: 2,
    limit: 10,
  });
  
  return {
    firstPage,
    secondPage,
  };
}

// Cursor-based pagination for large datasets
async function cursorPagination() {
  let cursor = null;
  const allItems = [];
  
  // Loop until we've fetched all items
  do {
    const response = await client.items.list({
      limit: 100,
      cursor: cursor,
    });
    
    allItems.push(...response.data);
    cursor = response.meta.nextCursor;
  } while (cursor);
  
  console.log('Total items fetched:', allItems.length);
  return allItems;
}

javascript

Performance Consideration

When fetching large datasets, always use pagination to avoid timeouts and excessive memory usage. The cursor-based pagination is recommended for iterating through large collections.

Advanced Queries

For complex data requirements, you can use our advanced query capabilities:

import { Client } from '@acme/sdk';

const client = new Client({
  apiKey: 'YOUR_API_KEY',
});

// Field selection (only fetch specific fields)
async function selectFields() {
  const items = await client.items.list({
    fields: ['id', 'name', 'price'],
  });
  
  return items;
}

// Nested data and relationships
async function fetchWithRelations() {
  const orders = await client.orders.list({
    include: ['customer', 'items'],
    fields: {
      orders: ['id', 'total', 'status'],
      customers: ['id', 'name', 'email'],
      items: ['id', 'name', 'quantity', 'price'],
    },
  });
  
  return orders;
}

// Aggregations and analytics
async function getAnalytics() {
  const analytics = await client.analytics.query({
    metrics: ['totalSales', 'orderCount', 'averageOrderValue'],
    dimensions: ['date', 'category'],
    filters: {
      dateRange: {
        start: '2023-01-01',
        end: '2023-12-31',
      },
    },
    sort: ['-totalSales'],
  });
  
  return analytics;
}

javascript

Was this page helpful?

Last updated on 3/19/2025