Skip to content

Commit 4237a8f

Browse files
committed
docs(api-server): add documentation for generic data management API
- Explain the purpose and benefits of the generic data endpoint - Describe how to use the API with examples - Introduce the Model Registry and its components - List supported models and usage restrictions
1 parent 13b41bc commit 4237a8f

File tree

1 file changed

+51
-0
lines changed

1 file changed

+51
-0
lines changed
Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
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

Comments
 (0)