Data Access API

The API provides a powerful and generic endpoint for performing CRUD (Create, Read, Update, Delete) operations on all core data models. This approach simplifies client-side code by providing a consistent interface for data interaction.

• Endpoint: /api/v1/data
• Authentication: Required (Bearer Token) for all methods.

The model Query Parameter

Every request to this endpoint must include a model query parameter to specify which data collection you are targeting.

• Example: GET /api/v1/data?model=headline

Supported Models

The following model names are supported:

• headline
• topic
• source
• country (supports specialized filtering by usage for ‘eventCountry’ or ‘headquarters’)
• 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 (i.e., they do not support POST, PUT, or DELETE requests). This is an intentional design choice. This foundational data is managed via the database seeding process.

Caution

Attempting to use an unsupported model name will result in a 400 Bad Request error.

Endpoints

List Items (Collection)

Retrieves a paginated list of items for a specific model.

• Method: GET
• Path: /api/v1/data?model=<model_name>

Query Parameters

• filter (string, optional): A URL-encoded JSON string representing a MongoDB-style query.

  Special Filter for Country Model: 'usage'

  For the country model, the filter parameter supports a special usage key. This allows you to retrieve a curated list of countries that are relevant to existing content, rather than all countries globally. This is particularly useful for populating dynamic dropdowns or filters in client applications.

  • filter={"usage":"eventCountry"}: Returns countries referenced as eventCountry in headlines.
  • filter={"usage":"headquarters"}: Returns countries referenced as headquarters in sources.

  When using the usage filter for the country model, the response will not be paginated and will return the complete filtered set of countries.

• sort (string, optional): A comma-separated list of fields to sort by (e.g., createdAt:desc,title:asc).

• limit (integer, optional): The maximum number of items to return.

• cursor (string, optional): The pagination cursor from a previous response to fetch the next page.

Note

Malformed filter or sort parameters will result in a 400 Bad Request error with a descriptive message.

Simple Filter

Request:

GET /api/v1/data?model=headline&filter={"status":"active"}

This fetches all headlines where the status field is "active".

Advanced Filter & Sort

Request:

GET /api/v1/data?model=headline&filter={"topic.id":{"$in":["topicId1","topicId2"]}}&sort=createdAt:desc

This fetches headlines belonging to specific topics, sorted by creation date.

Country Usage Filter

Request:

GET /api/v1/data?model=country&filter={"usage":"eventCountry"}

This fetches all countries that are referenced as ‘event countries’ in headlines.

• Success Response:
  • 200 OK: Returns a standard success response with a PaginatedResponse<T> object as the data payload.

Create Item

Creates a new item for a specific model.

• Method: POST

• Path: /api/v1/data?model=<model_name>

• Body (JSON): The JSON representation of the model to create. The id, createdAt, and updatedAt fields will be automatically generated by the server and should be omitted from the request body.

• Success Response:

  • 201 Created: Returns a standard success response with the newly created item object as the data payload.

Read Item

Retrieves a single item by its unique ID.

• Method: GET

• Path: /api/v1/data/<item_id>?model=<model_name>

• Success Response:

  • 200 OK: Returns a standard success response with the requested item object as the data payload.

• Error Responses:

  • 404 Not Found: The item with the specified ID does not exist.

Update Item

Updates an existing item by its unique ID.

• Method: PUT
• Path: /api/v1/data/<item_id>?model=<model_name>
• Body (JSON): The full JSON representation of the model with the updated fields.

Partial Updates for Users

When updating a user model, the API enforces a secure partial update mechanism. Non-admin users can only modify specific, whitelisted fields (such as feedActionStatus). Any attempts to change sensitive fields like appRole or email will be ignored, ensuring data integrity.

• Success Response:

  • 200 OK: Returns a standard success response with the updated item object as the data payload.

• Error Responses:

  • 404 Not Found: The item with the specified ID does not exist.

Delete Item

Deletes an item by its unique ID.

• Method: DELETE

• Path: /api/v1/data/<item_id>?model=<model_name>

• Success Response:

  • 204 No Content: The item was successfully deleted.

• Error Responses:

  • 404 Not Found: The item with the specified ID does not exist.