Merge pull request #18 from flutter-news-app-full-source-code/sync-api-docs

Sync api docs

Author: fulleni

src/content/docs/api-server/architecture/data-access-flow.mdx

@@ -40,7 +40,7 @@ This flow applies to requests for a collection of items.
     This crucial middleware uses the `ModelConfig` to determine the required permission for a `GET` collection request. It checks if the authenticated user has this permission. If not, a `403 Forbidden` error is thrown.
 
 6.  **Route Handler (`/routes/api/v1/data/index.dart`)**
-    The request finally reaches the handler. The handler uses the `DataOperationRegistry` to find the correct `readAll` function for the specified model and executes it. For the `country` model, if a `usage` filter is present, the request is delegated to the `CountryService` for specialized, non-paginated results; otherwise, it proceeds with standard pagination and sorting.
+    The request finally reaches the handler. The handler uses the `DataOperationRegistry` to find the correct `readAll` function for the specified model and executes it.
 
 7.  **Response**
     The handler wraps the data from the repository in a standard `SuccessApiResponse` and sends it back to the client.

src/content/docs/api-server/features/data-management-api.mdx

@@ -29,10 +29,17 @@ GET /api/v1/data?model=country&filter={"usage":"eventCountry"}
 ```
 This fetches countries that are referenced as 'event countries' in headlines. Similarly, `filter={"usage":"headquarters"}` can be used to fetch countries that are headquarters for sources.
 
-<Aside type="note" title="Why use the 'usage' filter for countries?">
-The `usage` filter for the `country` model is designed to enhance the client-side user experience and optimize data retrieval. Instead of fetching a comprehensive list of all countries globally, this filter allows client applications to retrieve only those countries that are *relevant* to existing content.
+**Example: Fetching countries by name**
+```http
+GET /api/v1/data?model=country&filter={"name":"United"}
+```
+This fetches countries whose names contain "United", supporting partial and case-insensitive matches.
+
+<Aside type="note" title="Specialized Filters for Countries: 'usage' and 'name'">
+The `country` model supports two specialized filters: `usage` and `name`.
 
-For instance, when a user wants to filter headlines by the country where the news event occurred, it's often more practical to present a list of countries for which actual headlines exist. Similarly, when filtering by the headquarters of news sources, displaying only countries that host active sources provides a more focused and actionable selection. This approach avoids presenting users with a long list of irrelevant options, streamlining navigation and improving the efficiency of data display.
+-   The `usage` filter is designed to enhance the client-side user experience and optimize data retrieval. Instead of fetching a comprehensive list of all countries globally, this filter allows client applications to retrieve only those countries that are *relevant* to existing content. For instance, when a user wants to filter headlines by the country where the news event occurred, it's often more practical to present a list of countries for which actual headlines exist. Similarly, when filtering by the headquarters of news sources, displaying only countries that host active sources provides a more focused and actionable selection. This approach avoids presenting users with a long list of irrelevant options, streamlining navigation and improving the efficiency of data display.
+-   The `name` filter allows users to search for countries using full or partial names, supporting case-insensitive matches. This is particularly useful for search functionalities, enabling users to quickly find countries by typing part of their name.
 </Aside>
 
 ### The Dual Registry System
@@ -53,7 +60,7 @@ The generic data endpoint can manage the following models out-of-the-box:
 -   `headline`
 -   `topic`
 -   `source`
--   `country` (supports specialized filtering by `usage` for 'eventCountry' or 'headquarters')
+-   `country`
 -   `language`
 -   `user`
 -   `user_app_settings`