|
| 1 | +--- |
| 2 | +title: 'Feature: Generic Data API' |
| 3 | +description: An explanation of the powerful, model-driven generic data endpoint for managing all application content. |
| 4 | +--- |
| 5 | + |
| 6 | +import { Aside } from '@astrojs/starlight/components'; |
| 7 | + |
| 8 | +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. |
| 9 | + |
| 10 | +This approach simplifies the API surface, reduces code duplication, and makes the system highly extensible. |
| 11 | + |
| 12 | +### How It Works |
| 13 | + |
| 14 | +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. |
| 15 | + |
| 16 | +**Example: Fetching all headlines** |
| 17 | +```http |
| 18 | +GET /api/v1/data?model=headline |
| 19 | +``` |
| 20 | + |
| 21 | +**Example: Fetching a single topic by its ID** |
| 22 | +```http |
| 23 | +GET /api/v1/data/some-topic-id?model=topic |
| 24 | +``` |
| 25 | + |
| 26 | +### The Model Registry |
| 27 | + |
| 28 | +The magic behind this generic endpoint is the **Model Registry** (`model_registry.dart`). This is a central map that links the string name of a model (e.g., `"headline"`) to a configuration object (`ModelConfig`). |
| 29 | + |
| 30 | +Each `ModelConfig` contains all the information the generic endpoint needs to handle a specific model, including: |
| 31 | +- **Deserialization:** A function to convert incoming JSON into the correct Dart object. |
| 32 | +- **ID Extraction:** A function to get the unique ID from a model instance. |
| 33 | +- **Ownership Information:** A function to identify the owner of a user-specific item (like `user_app_settings`). |
| 34 | +- **Authorization Rules:** A detailed permission configuration for every HTTP method (GET, POST, PUT, DELETE), specifying who is allowed to perform each action. |
| 35 | + |
| 36 | +### Supported Models |
| 37 | + |
| 38 | +The generic data endpoint can manage the following models out-of-the-box: |
| 39 | +- `headline` |
| 40 | +- `topic` |
| 41 | +- `source` |
| 42 | +- `country` |
| 43 | +- `user` |
| 44 | +- `user_app_settings` |
| 45 | +- `user_content_preferences` |
| 46 | +- `remote_config` |
| 47 | +- `dashboard_summary` |
| 48 | + |
| 49 | +<Aside type="note"> |
| 50 | +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 `ModelConfig` for each model. |
| 51 | +</Aside> |
0 commit comments