Backend API Documentation

Backend API Documentation #

This section provides detailed information about the NewsFeed backend API endpoints.

API Overview #

The NewsFeed API is built using FastAPI and follows RESTful principles. All API endpoints are prefixed with /api.

Authentication #

Most API endpoints require authentication. The API uses Casdoor for authentication and authorization.

To authenticate:

  1. Obtain an access token from the Casdoor authentication endpoint

  2. Include the token in the Authorization header of your requests:

    Authorization: Bearer <your_token>
    

API Endpoints #

Articles #

EndpointMethodDescription
/api/articlesGETList articles with pagination
/api/articles/{id}GETGet article by ID
/api/articles/searchGETSearch articles
/api/articles/latestGETGet latest articles
/api/articles/popularGETGet popular articles

List Articles #

GET /api/articles

Query parameters:

  • page: Page number (default: 1)
  • limit: Items per page (default: 20)
  • category: Filter by category
  • source: Filter by source
  • from_date: Filter by date (format: YYYY-MM-DD)
  • to_date: Filter by date (format: YYYY-MM-DD)

Categories #

EndpointMethodDescription
/api/categoriesGETList all categories
/api/categoriesPOSTCreate a new category (admin only)
/api/categories/{id}GETGet category by ID
/api/categories/{id}PUTUpdate a category (admin only)
/api/categories/{id}DELETEDelete a category (admin only)
/api/categories/{id}/articlesGETGet articles in a category

Sources #

EndpointMethodDescription
/api/sourcesGETList all sources
/api/sourcesPOSTAdd a new source (admin only)
/api/sources/{id}GETGet source by ID
/api/sources/{id}PUTUpdate a source (admin only)
/api/sources/{id}DELETEDelete a source (admin only)
/api/sources/{id}/articlesGETGet articles from a source
EndpointMethodDescription
/api/related/{article_id}GETGet related articles
/api/relatedPOSTCreate related article connection (admin only)
/api/related/{id}DELETEDelete related article connection (admin only)

Thumbnails #

EndpointMethodDescription
/api/thumbnails/{article_id}GETGet article thumbnail

Admin #

EndpointMethodDescription
/api/admin/rebuildPOSTTrigger system rebuild (admin only)
/api/admin/settingsGETGet system settings (admin only)
/api/admin/settingsPUTUpdate system settings (admin only)

Response Format #

All API responses follow a standard format:

{
  "status": "success",
  "data": {
    // Response data here
  },
  "message": "Optional message"
}

For error responses:

{
  "status": "error",
  "error": {
    "code": "ERROR_CODE",
    "message": "Error message"
  }
}

Rate Limiting #

The API implements rate limiting to prevent abuse. Limits are:

  • 100 requests per minute for authenticated users
  • 20 requests per minute for unauthenticated users

When rate limited, the API will return a 429 status code.