Add pagination support to list endpoints

PAGINATION.md

@@ -0,0 +1,120 @@
+# Pagination Support
+
+## Overview
+
+The MythAPI now supports pagination for all list-returning endpoints. This improves performance and usability when dealing with large datasets.
+
+## Usage
+
+### Query Parameters
+
+All list endpoints now accept optional pagination parameters:
+
+- `page` - The page number (1-based). Default: returns all results if not specified
+- `pageSize` - The number of items per page. Default: 10, Maximum: 100
+
+### Examples
+
+#### Without Pagination (Backward Compatible)
+```bash
+# Returns all gods
+GET /api/v1/gods
+
+# Returns all mythologies  
+GET /api/v1/mythologies
+```
+
+#### With Pagination
+```bash
+# Returns first page with 10 items (default page size)
+GET /api/v1/gods?page=1
+
+# Returns second page with 5 items per page
+GET /api/v1/gods?page=2&pageSize=5
+
+# Returns first page of mythologies with 20 items
+GET /api/v1/mythologies?page=1&pageSize=20
+```
+
+## Response Format
+
+### Non-Paginated Response
+When pagination parameters are not provided, the response is a simple list:
+```json
+[
+  {
+    "id": 1,
+    "name": "Zeus",
+    "description": "God of the sky",
+    "mythologyId": 1,
+    "aliases": []
+  },
+  ...
+]
+```
+
+### Paginated Response
+When pagination parameters are provided, the response includes metadata:
+```json
+{
+  "items": [
+    {
+      "id": 1,
+      "name": "Zeus",
+      "description": "God of the sky",
+      "mythologyId": 1,
+      "aliases": []
+    },
+    ...
+  ],
+  "page": 1,
+  "pageSize": 10,
+  "totalCount": 42,
+  "totalPages": 5,
+  "hasNext": true,
+  "hasPrevious": false
+}
+```
+
+### Response Fields
+
+- `items` - Array of items for the current page
+- `page` - Current page number (1-based)
+- `pageSize` - Number of items per page
+- `totalCount` - Total number of items across all pages
+- `totalPages` - Total number of pages available
+- `hasNext` - Boolean indicating if there's a next page
+- `hasPrevious` - Boolean indicating if there's a previous page
+
+## Validation
+
+The API automatically validates and corrects invalid pagination parameters:
+
+- `page` values less than 1 are automatically set to 1
+- `pageSize` values greater than 100 are automatically capped at 100
+- `pageSize` values less than 1 are automatically set to the default (10)
+
+## Endpoints Supporting Pagination
+
+The following endpoints support pagination:
+
+1. **GET /api/v1/gods** - List all gods
+2. **GET /api/v1/mythologies** - List all mythologies
+
+## Implementation Notes
+
+- Pagination is implemented at the database level for optimal performance
+- Uses Entity Framework's `Skip()` and `Take()` methods
+- Eager loading is used to avoid N+1 query problems
+- Results are ordered by ID to ensure consistent pagination
+
+## Backward Compatibility
+
+Existing clients that don't provide pagination parameters will continue to work as before, receiving the complete list of items. This ensures no breaking changes for existing integrations.
+
+## Best Practices
+
+1. **Use appropriate page sizes**: Balance between reducing the number of requests and keeping response sizes manageable
+2. **Handle edge cases**: Always check `hasNext` and `hasPrevious` before navigating
+3. **Cache when possible**: If data doesn't change frequently, consider caching paginated results
+4. **Consistent parameters**: Use the same page size across related requests for better caching

README.md

@@ -488,6 +488,21 @@ app.UseSwaggerUI();
 app.Run();
 ```
 
+# Features
+
+## Pagination Support
+
+All list-returning endpoints now support optional pagination to improve performance and usability. See [PAGINATION.md](PAGINATION.md) for detailed documentation.
+
+### Quick Example
+```bash
+# Get first page with 10 items
+GET /api/v1/gods?page=1&pageSize=10
+
+# Get all items (backward compatible)
+GET /api/v1/gods
+```
+
 # Future work
 
 - Improve Bicep scripts

src/Common/Models/PagedResult.cs

@@ -0,0 +1,43 @@
+namespace MythApi.Common.Models;
+
+/// <summary>
+/// Represents a paginated result set
+/// </summary>
+/// <typeparam name="T">The type of items in the result</typeparam>
+public class PagedResult<T>
+{
+    /// <summary>
+    /// The items in the current page
+    /// </summary>
+    public IList<T> Items { get; set; } = new List<T>();
+
+    /// <summary>
+    /// Current page number (1-based)
+    /// </summary>
+    public int Page { get; set; }
+
+    /// <summary>
+    /// Number of items per page
+    /// </summary>
+    public int PageSize { get; set; }
+
+    /// <summary>
+    /// Total number of items across all pages
+    /// </summary>
+    public int TotalCount { get; set; }
+
+    /// <summary>
+    /// Total number of pages
+    /// </summary>
+    public int TotalPages => (int)Math.Ceiling(TotalCount / (double)PageSize);
+
+    /// <summary>
+    /// Whether there is a previous page
+    /// </summary>
+    public bool HasPrevious => Page > 1;
+
+    /// <summary>
+    /// Whether there is a next page
+    /// </summary>
+    public bool HasNext => Page < TotalPages;
+}

src/Common/Models/PaginationParameters.cs

@@ -0,0 +1,36 @@
+namespace MythApi.Common.Models;
+
+/// <summary>
+/// Parameters for pagination requests
+/// </summary>
+public class PaginationParameters
+{
+    private const int MaxPageSize = 100;
+    private const int DefaultPageSize = 10;
+
+    private int _pageSize = DefaultPageSize;
+    private int _page = 1;
+
+    /// <summary>
+    /// Page number (1-based)
+    /// </summary>
+    public int Page
+    {
+        get => _page;
+        set => _page = value < 1 ? 1 : value;
+    }
+
+    /// <summary>
+    /// Number of items per page (default: 10, max: 100)
+    /// </summary>
+    public int PageSize
+    {
+        get => _pageSize;
+        set => _pageSize = value > MaxPageSize ? MaxPageSize : (value < 1 ? DefaultPageSize : value);
+    }
+
+    /// <summary>
+    /// Calculate the number of items to skip
+    /// </summary>
+    public int Skip => (Page - 1) * PageSize;
+}

src/Endpoints/v1/Gods.cs

@@ -1,6 +1,7 @@
 using Microsoft.AspNetCore.Mvc;
 using MythApi.Gods.Interfaces;
 using MythApi.Common.Database.Models;
+using MythApi.Common.Models;
 using MythApi.Gods.Models;
 
 namespace MythApi.Endpoints.v1;
@@ -10,13 +11,34 @@ public static void RegisterGodEndpoints(this IEndpointRouteBuilder endpoints) {
         var gods = endpoints.MapGroup("/api/v1/gods");
 
 
-        gods.MapGet("", GetAlllGods);
+        gods.MapGet("", GetAllGods);
         gods.MapGet("{id}", (int id, IGodRepository repository) => repository.GetGodAsync(new GodParameter(id)));
         gods.MapGet("search/{name}", (string name, IGodRepository repository, [FromQuery] bool includeAliases = false) => repository.GetGodByNameAsync(new GodByNameParameter(name, includeAliases)));
         gods.MapPost("", AddOrUpdateGods);
     }
 
     public static Task<List<God>> AddOrUpdateGods(List<GodInput> gods, IGodRepository repository) => repository.AddOrUpdateGods(gods);
 
-    public static Task<IList<God>> GetAlllGods(IGodRepository repository) => repository.GetAllGodsAsync();
+    public static async Task<IResult> GetAllGods(
+        IGodRepository repository,
+        [FromQuery] int? page = null,
+        [FromQuery] int? pageSize = null)
+    {
+        // If pagination parameters are not provided, return all gods (backward compatibility)
+        if (page == null && pageSize == null)
+        {
+            var allGods = await repository.GetAllGodsAsync();
+            return Results.Ok(allGods);
+        }
+
+        // Use pagination
+        var pagination = new PaginationParameters
+        {
+            Page = page ?? 1,
+            PageSize = pageSize ?? 10
+        };
+
+        var pagedResult = await repository.GetAllGodsAsync(pagination);
+        return Results.Ok(pagedResult);
+    }
 }

src/Endpoints/v1/Mythologies.cs

@@ -1,4 +1,6 @@
+using Microsoft.AspNetCore.Mvc;
 using MythApi.Common.Database.Models;
+using MythApi.Common.Models;
 using MythApi.Mythologies.Interfaces;
 
 public static class Mythologies
@@ -10,5 +12,26 @@ public static void RegisterMythologiesEndpoints(this IEndpointRouteBuilder endpo
         mythologies.MapGet("", GetAllMythologies);
     }
 
-    public static Task<IList<Mythology>> GetAllMythologies(IMythologyRepository repository) => repository.GetAllMythologiesAsync();
+    public static async Task<IResult> GetAllMythologies(
+        IMythologyRepository repository,
+        [FromQuery] int? page = null,
+        [FromQuery] int? pageSize = null)
+    {
+        // If pagination parameters are not provided, return all mythologies (backward compatibility)
+        if (page == null && pageSize == null)
+        {
+            var allMythologies = await repository.GetAllMythologiesAsync();
+            return Results.Ok(allMythologies);
+        }
+
+        // Use pagination
+        var pagination = new PaginationParameters
+        {
+            Page = page ?? 1,
+            PageSize = pageSize ?? 10
+        };
+
+        var pagedResult = await repository.GetAllMythologiesAsync(pagination);
+        return Results.Ok(pagedResult);
+    }
 }

src/Gods/DBRepositories/GodRepository.cs

@@ -2,6 +2,7 @@
 using MythApi.Gods.Interfaces;
 using MythApi.Common.Database.Models;
 using MythApi.Common.Database;
+using MythApi.Common.Models;
 using MythApi.Gods.Models;
 
 namespace MythApi.Gods.DBRepositories;
@@ -44,14 +45,32 @@ public async Task<List<God>> AddOrUpdateGods(List<GodInput> gods)
 
     public async Task<IList<God>> GetAllGodsAsync()
     {
-        var gods = await _context.Gods.ToListAsync();
-        foreach (var god in gods)
-        {
-            _context.Entry(god).Collection(x => x.Aliases).Load();
-        }
+        var gods = await _context.Gods
+            .Include(g => g.Aliases)
+            .ToListAsync();
         return gods;
     }
 
+    public async Task<PagedResult<God>> GetAllGodsAsync(PaginationParameters pagination)
+    {
+        var totalCount = await _context.Gods.CountAsync();
+
+        var gods = await _context.Gods
+            .Include(g => g.Aliases)
+            .OrderBy(g => g.Id)
+            .Skip(pagination.Skip)
+            .Take(pagination.PageSize)
+            .ToListAsync();
+
+        return new PagedResult<God>
+        {
+            Items = gods,
+            Page = pagination.Page,
+            PageSize = pagination.PageSize,
+            TotalCount = totalCount
+        };
+    }
+
     public async Task<God> GetGodAsync(GodParameter parameter)
     {
         return await _context.Gods.FirstAsync(x => x.Id == parameter.Id);

src/Gods/Interfaces/IGodRepository.cs

@@ -1,11 +1,14 @@
 using MythApi.Common.Database.Models;
+using MythApi.Common.Models;
 using MythApi.Gods.Models;
 
 namespace MythApi.Gods.Interfaces;
 
 public interface IGodRepository{
     public Task<IList<God>> GetAllGodsAsync();
 
+    public Task<PagedResult<God>> GetAllGodsAsync(PaginationParameters pagination);
+
     public Task<God> GetGodAsync(GodParameter parameter);
 
     public Task<List<God>> GetGodByNameAsync(GodByNameParameter parameter);

src/Gods/Mocks/GodRepository.cs

@@ -1,5 +1,6 @@
 using MythApi.Gods.Interfaces;
 using MythApi.Common.Database.Models;
+using MythApi.Common.Models;
 using MythApi.Gods.Models;
 
 namespace MythApi.Gods.Mocks;
@@ -40,6 +41,23 @@ public Task<IList<God>> GetAllGodsAsync()
         return Task.FromResult(gods as IList<God>);
     }
 
+    public Task<PagedResult<God>> GetAllGodsAsync(PaginationParameters pagination)
+    {
+        var totalCount = gods.Count;
+        var items = gods
+            .Skip(pagination.Skip)
+            .Take(pagination.PageSize)
+            .ToList();
+
+        return Task.FromResult(new PagedResult<God>
+        {
+            Items = items,
+            Page = pagination.Page,
+            PageSize = pagination.PageSize,
+            TotalCount = totalCount
+        });
+    }
+
     public Task<God> GetGodAsync(GodParameter parameter)
     {
         return Task.FromResult(gods[parameter.Id]);