Skip to content

Commit b265c38

Browse files
committed
docs(api-server): enhance country data API examples and documentation
- Add example for fetching countries by name - Introduce 'name' filter for country model - Refactor Aside component to explain both 'usage' and 'name' filters - Update country model description to include both filters
1 parent 9a84682 commit b265c38

File tree

1 file changed

+11
-4
lines changed

1 file changed

+11
-4
lines changed

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

Lines changed: 11 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -29,10 +29,17 @@ GET /api/v1/data?model=country&filter={"usage":"eventCountry"}
2929
```
3030
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.
3131

32-
<Aside type="note" title="Why use the 'usage' filter for countries?">
33-
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.
32+
**Example: Fetching countries by name**
33+
```http
34+
GET /api/v1/data?model=country&filter={"name":"United"}
35+
```
36+
This fetches countries whose names contain "United", supporting partial and case-insensitive matches.
37+
38+
<Aside type="note" title="Specialized Filters for Countries: 'usage' and 'name'">
39+
The `country` model supports two specialized filters: `usage` and `name`.
3440

35-
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.
41+
- 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.
42+
- 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.
3643
</Aside>
3744

3845
### The Dual Registry System
@@ -53,7 +60,7 @@ The generic data endpoint can manage the following models out-of-the-box:
5360
- `headline`
5461
- `topic`
5562
- `source`
56-
- `country` (supports specialized filtering by `usage` for 'eventCountry' or 'headquarters')
63+
- `country`
5764
- `language`
5865
- `user`
5966
- `user_app_settings`

0 commit comments

Comments
 (0)