From 64bd0130d3b89ad9dbbe50f17d81b6cf05ccf4d0 Mon Sep 17 00:00:00 2001 From: Wang Qi Date: Wed, 13 May 2026 11:44:40 +0800 Subject: [PATCH] Add REST API backward compatibility (#14872) ### What problem does this PR solve? Add REST API backward compatibility ### Type of change - [x] Bug Fix (non-breaking change which fixes an issue) --- api/apps/backward_compat.py | 151 +++++++++++++++++++++++++- docs/references/http_api_reference.md | 26 +++++ 2 files changed, 173 insertions(+), 4 deletions(-) diff --git a/api/apps/backward_compat.py b/api/apps/backward_compat.py index a2c950158..feaedc6d6 100644 --- a/api/apps/backward_compat.py +++ b/api/apps/backward_compat.py @@ -22,8 +22,15 @@ new API implementation. Deprecated APIs and their replacements: - POST /api/v1/agents/{agent_id}/completions -> POST /api/v1/agents/chat/completion +- POST /api/v1/agents_openai/{agent_id}/chat/completions -> POST /api/v1/agents/chat/completions - POST /api/v1/chats/{chat_id}/completions -> POST /api/v1/chat/completions - POST /api/v1/chats_openai/{chat_id}/chat/completions -> POST /api/v1/openai/{chat_id}/chat/completions +- GET /api/v1/datasets/{dataset_id}/knowledge_graph -> GET /api/v1/datasets/{dataset_id}/graph +- DELETE /api/v1/datasets/{dataset_id}/knowledge_graph -> DELETE /api/v1/datasets/{dataset_id}/graph +- POST /api/v1/datasets/{dataset_id}/run_graphrag -> POST /api/v1/datasets/{dataset_id}/index?type=graph +- GET /api/v1/datasets/{dataset_id}/trace_graphrag -> GET /api/v1/datasets/{dataset_id}/index?type=graph +- POST /api/v1/datasets/{dataset_id}/run_raptor -> POST /api/v1/datasets/{dataset_id}/index?type=raptor +- GET /api/v1/datasets/{dataset_id}/trace_raptor -> GET /api/v1/datasets/{dataset_id}/index?type=raptor - PUT /api/v1/chats/{chat_id}/sessions/{session_id} -> PATCH /api/v1/chats/{chat_id}/sessions/{session_id} - DELETE /api/v1/chats -> DELETE /api/v1/chats/{chat_id} (with body) - POST /api/v1/file/convert -> POST /api/v1/files/link-to-datasets @@ -41,16 +48,21 @@ import logging from quart import Blueprint, jsonify, request from api.apps import login_required -from api.apps.restful_apis import chat_api, file_api, file2document_api, chunk_api, openai_api, document_api +from api.apps.restful_apis import agent_api, chat_api, chunk_api, dataset_api, document_api, file2document_api, file_api, openai_api from api.apps.restful_apis.system_api import run_health_checks -from api.apps.restful_apis import agent_api -from api.apps.services import file_api_service -from api.utils.api_utils import get_data_error_result, get_json_result, add_tenant_id_to_kwargs +from api.apps.services import dataset_api_service, file_api_service +from api.utils.api_utils import add_tenant_id_to_kwargs, get_data_error_result, get_json_result, get_request_json manager = Blueprint("backward_compat", __name__) legacy_v1_manager = Blueprint("backward_compat_legacy_v1", __name__) +def _index_result(success, result): + if success: + return get_json_result(data=result) + return get_data_error_result(message=result) + + # ============================================================================= # System APIs # ============================================================================= @@ -110,6 +122,137 @@ async def deprecated_openai_chat_completions(chat_id): return await openai_api.openai_chat_completions(chat_id) +@manager.route("/agents_openai//chat/completions", methods=["POST"]) +@login_required +@add_tenant_id_to_kwargs +async def deprecated_agents_openai_chat_completions(agent_id, tenant_id=None): + """ + Deprecated: Use POST /api/v1/agents/chat/completions with openai-compatible=true instead. + + Old path: POST /api/v1/agents_openai/{agent_id}/chat/completions + New path: POST /api/v1/agents/chat/completions + """ + logging.warning( + "API endpoint /api/v1/agents_openai/%s/chat/completions is deprecated. " + "Please use /api/v1/agents/chat/completions with `openai-compatible` instead.", + agent_id, + ) + req = dict(await get_request_json()) + req["openai-compatible"] = True + request._cached_payload = req + return await agent_api.agent_chat_completion(tenant_id=tenant_id, agent_id=agent_id) + + +# ============================================================================= +# Dataset Graph and Index APIs +# ============================================================================= + +@manager.route("/datasets//knowledge_graph", methods=["GET"]) +@login_required +async def deprecated_get_knowledge_graph(dataset_id): + """ + Deprecated: Use GET /api/v1/datasets/{dataset_id}/graph instead. + + Old path: GET /api/v1/datasets/{dataset_id}/knowledge_graph + New path: GET /api/v1/datasets/{dataset_id}/graph + """ + logging.warning( + "API endpoint /api/v1/datasets/%s/knowledge_graph is deprecated. " + "Please use /api/v1/datasets/%s/graph instead.", + dataset_id, dataset_id, + ) + return await dataset_api.get_knowledge_graph(dataset_id=dataset_id) + + +@manager.route("/datasets//knowledge_graph", methods=["DELETE"]) +@login_required +async def deprecated_delete_knowledge_graph(dataset_id): + """ + Deprecated: Use DELETE /api/v1/datasets/{dataset_id}/graph instead. + + Old path: DELETE /api/v1/datasets/{dataset_id}/knowledge_graph + New path: DELETE /api/v1/datasets/{dataset_id}/graph + """ + logging.warning( + "API endpoint DELETE /api/v1/datasets/%s/knowledge_graph is deprecated. " + "Please use DELETE /api/v1/datasets/%s/graph instead.", + dataset_id, dataset_id, + ) + return await dataset_api.delete_knowledge_graph(dataset_id=dataset_id) + + +@manager.route("/datasets//run_graphrag", methods=["POST"]) +@login_required +@add_tenant_id_to_kwargs +async def deprecated_run_graphrag(dataset_id, tenant_id=None): + """ + Deprecated: Use POST /api/v1/datasets/{dataset_id}/index?type=graph instead. + + Old path: POST /api/v1/datasets/{dataset_id}/run_graphrag + New path: POST /api/v1/datasets/{dataset_id}/index?type=graph + """ + logging.warning( + "API endpoint /api/v1/datasets/%s/run_graphrag is deprecated. " + "Please use /api/v1/datasets/%s/index?type=graph instead.", + dataset_id, dataset_id, + ) + return _index_result(*dataset_api_service.run_index(dataset_id, tenant_id, "graph")) + + +@manager.route("/datasets//trace_graphrag", methods=["GET"]) +@login_required +@add_tenant_id_to_kwargs +async def deprecated_trace_graphrag(dataset_id, tenant_id=None): + """ + Deprecated: Use GET /api/v1/datasets/{dataset_id}/index?type=graph instead. + + Old path: GET /api/v1/datasets/{dataset_id}/trace_graphrag + New path: GET /api/v1/datasets/{dataset_id}/index?type=graph + """ + logging.warning( + "API endpoint /api/v1/datasets/%s/trace_graphrag is deprecated. " + "Please use /api/v1/datasets/%s/index?type=graph instead.", + dataset_id, dataset_id, + ) + return _index_result(*dataset_api_service.trace_index(dataset_id, tenant_id, "graph")) + + +@manager.route("/datasets//run_raptor", methods=["POST"]) +@login_required +@add_tenant_id_to_kwargs +async def deprecated_run_raptor(dataset_id, tenant_id=None): + """ + Deprecated: Use POST /api/v1/datasets/{dataset_id}/index?type=raptor instead. + + Old path: POST /api/v1/datasets/{dataset_id}/run_raptor + New path: POST /api/v1/datasets/{dataset_id}/index?type=raptor + """ + logging.warning( + "API endpoint /api/v1/datasets/%s/run_raptor is deprecated. " + "Please use /api/v1/datasets/%s/index?type=raptor instead.", + dataset_id, dataset_id, + ) + return _index_result(*dataset_api_service.run_index(dataset_id, tenant_id, "raptor")) + + +@manager.route("/datasets//trace_raptor", methods=["GET"]) +@login_required +@add_tenant_id_to_kwargs +async def deprecated_trace_raptor(dataset_id, tenant_id=None): + """ + Deprecated: Use GET /api/v1/datasets/{dataset_id}/index?type=raptor instead. + + Old path: GET /api/v1/datasets/{dataset_id}/trace_raptor + New path: GET /api/v1/datasets/{dataset_id}/index?type=raptor + """ + logging.warning( + "API endpoint /api/v1/datasets/%s/trace_raptor is deprecated. " + "Please use /api/v1/datasets/%s/index?type=raptor instead.", + dataset_id, dataset_id, + ) + return _index_result(*dataset_api_service.trace_index(dataset_id, tenant_id, "raptor")) + + # ============================================================================= # Chat Session APIs # ============================================================================= diff --git a/docs/references/http_api_reference.md b/docs/references/http_api_reference.md index 0d3c62878..973a319d4 100644 --- a/docs/references/http_api_reference.md +++ b/docs/references/http_api_reference.md @@ -27,6 +27,32 @@ A complete reference for RAGFlow's RESTful API. Before proceeding, please ensure --- +## Deprecated API Aliases + +The following v0.24.0 REST API paths are deprecated. They remain available through the backward compatibility layer, but new integrations should use the replacement endpoints. + +| Deprecated endpoint | Replacement endpoint | +|---------------------|----------------------| +| **POST** `/api/v1/chats_openai/{chat_id}/chat/completions` | **POST** `/api/v1/openai/{chat_id}/chat/completions` | +| **PUT** `/api/v1/chats/{chat_id}/sessions/{session_id}` | **PATCH** `/api/v1/chats/{chat_id}/sessions/{session_id}` | +| **POST** `/api/v1/chats/{chat_id}/completions` | **POST** `/api/v1/chat/completions` | +| **POST** `/api/v1/sessions/related_questions` | **POST** `/api/v1/chat/recommandation` | +| **PUT** `/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks/{chunk_id}` | **PATCH** `/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks/{chunk_id}` | +| **GET** `/v1/system/healthz` | **GET** `/api/v1/system/healthz` | +| **POST** `/api/v1/file/upload` | **POST** `/api/v1/files` | +| **POST** `/api/v1/file/create` | **POST** `/api/v1/files` | +| **GET** `/api/v1/file/list` | **GET** `/api/v1/files` | +| **GET** `/api/v1/file/root_folder` | **GET** `/api/v1/files` | +| **GET** `/api/v1/file/parent_folder` | **GET** `/api/v1/files/{file_id}/parent` | +| **GET** `/api/v1/file/all_parent_folder` | **GET** `/api/v1/files/{file_id}/ancestors` | +| **POST** `/api/v1/file/rm` | **DELETE** `/api/v1/files` | +| **POST** `/api/v1/file/rename` | **POST** `/api/v1/files/move` | +| **GET** `/api/v1/file/get/{file_id}` | **GET** `/api/v1/files/{file_id}` | +| **POST** `/api/v1/file/mv` | **POST** `/api/v1/files/move` | +| **POST** `/api/v1/file/convert` | **POST** `/api/v1/files/link-to-datasets` | + +--- + ## OpenAI-Compatible API ---