ht_api

🚀 Accelerate the development of your news application backend with ht_api, the dedicated API service for the Headlines Toolkit. Built on the high-performance Dart Frog framework, ht_api provides the essential server-side infrastructure specifically designed to power robust and feature-rich news applications.

ht_api is a core component of the Headlines Toolkit, a comprehensive, source-available ecosystem designed for building feature-rich news applications, which also includes a Flutter mobile app and a web-based content management dashboard.

✨ Key Capabilities

• 🔒 Flexible & Secure Authentication: Provide seamless user access with a unified system supporting passwordless email sign-in, anonymous guest accounts, and a secure, role-aware login flow for privileged dashboard users.

• ⚡️ Granular Role-Based Access Control (RBAC): Implement precise permissions with a dual-role system (appRole for application features, dashboardRole for admin functions) to control access to API features and data management capabilities.

• ⚙️ Synchronized App Settings: Ensure a consistent and personalized user experience across devices by effortlessly syncing application preferences like theme, language, font styles, and more.

• 👤 Personalized User Preferences: Enable richer user interactions by managing and syncing user-specific data such as saved headlines, followed sources, and followed topics tailored to individual users.

• 💾 Robust Data Management: Securely manage core news data (headlines, topics, sources) through a well-structured API that supports flexible querying and sorting for dynamic content presentation.

• 🌐 Dynamic Remote Configuration: Centrally manage application behavior—including ad frequency, feature flags, and maintenance status—without requiring a client-side update.

• 📊 Dynamic Dashboard Summary: Access real-time, aggregated metrics on key data points like total headlines, topics, and sources, providing an at-a-glance overview for administrative dashboards.

• 🔧 Solid Technical Foundation: Built with Dart and the high-performance Dart Frog framework, offering a maintainable codebase, standardized API responses, and built-in access control for developers.

🔌 API Endpoints

ht_api provides a clear and organized API surface under the /api/v1/ path. Key endpoint groups cover authentication, data access, and user settings.

For complete API specifications, detailed endpoint documentation, request/response schemas, and error codes, please refer to the dedicated documentation website [todo:Link to the docs website].

🔑 Access and Licensing

ht_api is source-available as part of the Headlines Toolkit ecosystem.

To acquire a commercial license for building unlimited news applications, please visit the Headlines Toolkit GitHub organization page for more details.

💻 Setup & Running

1. Prerequisites:

   • Dart SDK (>=3.0.0)
   • MongoDB (>=5.0 recommended)
   • Dart Frog CLI (dart pub global activate dart_frog_cli)

2. Configuration: Before running the server, you must configure the database connection by setting the DATABASE_URL environment variable.

   Create a .env file in the root of the project or export the variable in your shell:

   DATABASE_URL="mongodb://user:password@localhost:27017/ht_api_db"
   

3. Clone the repository:

   git clone https://github.com/headlines-toolkit/ht-api.git
   cd ht-api

4. Get dependencies:

   dart pub get

5. Run the development server:

   dart_frog dev

   The API will typically be available at http://localhost:8080. On startup, the server will connect to your MongoDB database and seed it with initial fixture data. This seeding process is idempotent (using upsert operations), so it can be run multiple times without creating duplicates.

   Note on Web Client Integration (CORS): To allow web applications (like the HT Dashboard) to connect to this API in production, the CORS_ALLOWED_ORIGIN environment variable must be set to the specific origin of your web application (e.g., https://your-dashboard.com).

   For local development, the API automatically allows any request originating from localhost on any port, so you do not need to set this variable.

✅ Testing

Ensure the API is robust and meets quality standards by running the test suite:

# Ensure very_good_cli is activated: dart pub global activate very_good_cli
very_good test --min-coverage 90

Aim for a minimum of 90% line coverage.