Skip to content

CATEGORIES_API_PAGINATION.md

Latest commit

 

History

History
263 lines (206 loc) · 6.99 KB

CATEGORIES_API_PAGINATION.md

File metadata and controls

263 lines (206 loc) · 6.99 KB
Raw

Categories API - Pagination, Caching & Image Links

Pagination

The Categories API now supports pagination to handle large datasets efficiently.

Pagination Parameters

  • page (optional): Page number (default: 1, minimum: 1)
  • per_page (optional): Items per page (default: 50, range: 1-100)

Pagination Response Format

All responses now include pagination metadata:

{
  "data": [
    "Technology",
    "News",
    "Entertainment"
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 50,
    "total": 25,
    "last_page": 1,
    "from": 1,
    "to": 25,
    "has_more_pages": false,
    "has_previous_pages": false
  }
}

Image Links

The Categories API now supports including image links for categories that can be used in mobile apps.

Image Links Parameters

  • include_images (optional): Include image URLs for categories (default: false)
  • X-Include-Images header: Alternative way to include image links

Image Links Response Format

When include_images=true is specified, categories will include image URLs:

{
  "data": [
    {
      "name": "Technology",
      "image_url": "https://example.com/tech-image.jpg"
    },
    {
      "name": "News",
      "image_url": "https://example.com/news-image.jpg"
    },
    {
      "name": "Entertainment"
    }
  ]
}

Categories without configured image links will not include the image_url field.

Combining Parameters

Image links can be combined with other parameters:

{
  "data": [
    {
      "name": "Technology",
      "podcast_count": 15,
      "image_url": "https://example.com/tech-image.jpg"
    },
    {
      "name": "News",
      "podcast_count": 8,
      "image_url": "https://example.com/news-image.jpg"
    }
  ]
}

Complete Parameter Reference

Query Parameters

  • live_only (optional): Filter for categories with live podcasts only
  • include_counts (optional): Include podcast counts for each category
  • include_images (optional): Include image URLs for each category
  • page (optional): Page number for pagination
  • per_page (optional): Items per page for pagination

Headers

  • X-Live-Only: Alternative to live_only parameter
  • X-Include-Counts: Alternative to include_counts parameter
  • X-Include-Images: Alternative to include_images parameter
  • Accept: Response format (application/json, application/xml, text/csv)

Pagination Examples

# Get first page with 10 items per page
curl "http://localhost:8000/api/categories?page=1&per_page=10"

# Get second page
curl "http://localhost:8000/api/categories?page=2&per_page=10"

# Combine with other filters
curl "http://localhost:8000/api/categories?live_only=true&include_counts=true&page=1&per_page=5"

Image Links Examples

# Get categories with image links
curl "http://localhost:8000/api/categories?include_images=true"

# Get live categories with image links
curl "http://localhost:8000/api/categories?live_only=true&include_images=true"

# Get categories with counts and image links
curl "http://localhost:8000/api/categories?include_counts=true&include_images=true"

# Using headers
curl -H "X-Include-Images: true" "http://localhost:8000/api/categories"

Caching

Cache Duration

  • Previous: 1 hour (60 minutes)
  • Current: 15 minutes

This shorter cache duration ensures more responsive updates when new podcasts are added or categories change.

Cache Keys

The API uses different cache keys based on the request parameters:

  • all_categories - Basic categories list
  • all_categories_with_counts - Categories with podcast counts
  • all_categories_with_images - Categories with image links
  • all_categories_with_counts_with_images - Categories with counts and image links
  • live_categories - Live-only categories
  • live_categories_with_counts - Live categories with counts
  • live_categories_with_images - Live categories with image links
  • live_categories_with_counts_with_images - Live categories with counts and image links

Cache Invalidation

Cache is automatically invalidated after 15 minutes. For immediate updates, you can:

  1. Wait for cache expiration
  2. Clear cache manually via admin interface
  3. Restart the application

Complete Example

# Get live categories with counts and image links, paginated, in XML format
curl -H "X-Live-Only: true" \
     -H "X-Include-Counts: true" \
     -H "X-Include-Images: true" \
     -H "Accept: application/xml" \
     "http://localhost:8000/api/categories?page=1&per_page=5"

Response:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <data>
    <item0>
      <name>Technology</name>
      <podcast_count>15</podcast_count>
      <image_url>https://example.com/tech-image.jpg</image_url>
    </item0>
    <item1>
      <name>News</name>
      <podcast_count>8</podcast_count>
      <image_url>https://example.com/news-image.jpg</image_url>
    </item1>
  </data>
  <pagination>
    <current_page>1</current_page>
    <per_page>5</per_page>
    <total>25</total>
    <last_page>5</last_page>
    <from>1</from>
    <to>5</to>
    <has_more_pages>true</has_more_pages>
    <has_previous_pages>false</has_previous_pages>
  </pagination>
</response>

JavaScript Examples

// Get paginated categories
async function getCategories(page = 1, perPage = 10) {
    const response = await fetch(`/api/categories?page=${page}&per_page=${perPage}`);
    const data = await response.json();
    
    console.log('Categories:', data.data);
    console.log('Pagination:', data.pagination);
    
    return data;
}

// Get live categories with counts and image links, paginated
async function getLiveCategoriesWithCountsAndImages(page = 1, perPage = 10) {
    const response = await fetch(`/api/categories?live_only=true&include_counts=true&include_images=true&page=${page}&per_page=${perPage}`);
    const data = await response.json();
    
    return data;
}

// Check if there are more pages
function hasMorePages(pagination) {
    return pagination.has_more_pages;
}

// Get next page
function getNextPage(currentPage) {
    return currentPage + 1;
}

// Extract image URLs from categories
function getCategoryImages(categories) {
    return categories
        .filter(category => category.image_url)
        .map(category => ({
            name: category.name,
            imageUrl: category.image_url
        }));
}

Best Practices

  1. Use appropriate page sizes: 10-50 items per page is usually optimal
  2. Cache responses: Implement client-side caching for better performance
  3. Handle pagination gracefully: Always check has_more_pages before requesting next page
  4. Optimize image loading: Only request image links when needed for UI display
  5. Fallback gracefully: Handle categories without image links in your UI

Admin Management

Category image links can be managed through the Adminix interface at /adminix/category-links. This allows administrators to:

  • Add image URLs for categories
  • Edit existing image URLs
  • Remove image URLs
  • View the JSON data stored in Redis
  • Refresh the categories list from the database