Feature: Generic Data API

A key architectural feature of the API server is its generic data endpoint, located at /api/v1/data. Instead of having separate endpoints for each data type (e.g., /headlines, /topics), this single, powerful endpoint can manage multiple data models through a simple query parameter.

This approach simplifies the API surface, reduces code duplication, and makes the system highly extensible.

How It Works

A client makes a standard REST request (GET, POST, PUT, DELETE) to the /api/v1/data endpoint and specifies the target data type using the ?model= query parameter.

Example: Fetching all headlines

GET /api/v1/data?model=headline

Example: Fetching a single topic by its ID

GET /api/v1/data/some-topic-id?model=topic

Example: Fetching countries by usage

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.

Example: Fetching countries by name

GET /api/v1/data?model=country&filter={"name":"United"}

This fetches countries whose names contain “United”, supporting partial and case-insensitive matches.

Specialized Filters for Countries: 'usage' and 'name'

The country model supports two specialized filters: usage and name.

• 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.

The Dual Registry System

The power behind this generic endpoint comes from two central registries:

1. The Model Registry (ModelRegistry): This registry defines the rules for each model. It maps a model name (e.g., "headline") to a configuration object that specifies authorization requirements, ownership details, and how to handle JSON data for that model.

2. The Data Operation Registry (DataOperationRegistry): This registry provides the actions. It maps a model name to the actual functions that perform the CRUD operations (Create, Read, Update, Delete).

Tip

For a detailed technical explanation of how these registries and the middleware work together, see the Architectural Deep Dive: Data Access Flow guide.

Supported Models

The generic data endpoint can manage the following models out-of-the-box:

• headline
• topic
• source
• country
• language
• user
• user_app_settings
• user_content_preferences
• remote_config
• dashboard_summary

Read-Only Models

The country and language models are configured to be read-only through the API. This is an intentional design choice. This foundational data is managed centrally via the database seeding process and is not intended to be modified by users.

Note

Some actions are intentionally unsupported through this generic endpoint for security or logical reasons. For example, creating a new user is handled exclusively by the dedicated /api/v1/auth/verify-code endpoint, not by a POST request to ?model=user. These restrictions are defined in the ModelRegistry for each model.