langgenius/dify
1
0
Fork 0
mirror of https://github.com/langgenius/dify.git synced 2026-07-21 20:15:31 -04:00
Code Issues 775 Packages Projects Releases 10 Wiki Activity

[PR #23700] Feature/refactor and workflow api #30362

New Issue
Open
opened 2026-02-21 20:47:21 -05:00 by yindo · 0 comments
yindo commented 2026-02-21 20:47:21 -05:00
Owner
Copy Link
Copy Source

Original Pull Request: https://github.com/langgenius/dify/pull/23700

State: open
Merged: No

Important

  1. Make sure you have read our CONTRIBUTING.md
  2. Ensure there is an associated issue and you have been assigned to it
  3. Use the correct syntax to link this PR: Fixes add API node-executions #23677

Fixes add API node-executions close #23677

Summary

This PR introduces two new Service API endpoints to enhance workflow monitoring and message management capabilities:

  1. Message Details API (GET /v1/messages/{message_id}) - Retrieve comprehensive message information by message ID
  2. Node Executions API (GET /v1/node-executions) - Get workflow run node execution list with detailed execution information

Additionally, this PR includes code quality improvements by removing unused Flask imports and formatting import statements.

Key Changes:

  • Added MessageDetailApi class in api/controllers/service_api/app/message.py
  • Added NodeExecutionsApi class in api/controllers/service_api/app/node_executions.py
  • Registered new API endpoints in service API routing
  • Removed unused Flask imports from service API modules
  • Applied consistent code formatting

API Endpoints Added:

1. GET /v1/messages/{message_id}

  • Purpose: Fetch detailed message information including content, metadata, and execution context
  • Authentication: Requires valid API key
  • Response: Complete message object with timestamps, token counts, and source information

2. GET /v1/node-executions

  • Purpose: Retrieve workflow node execution details for monitoring and debugging
  • Parameters: workflow_run_id (required), limit, offset
  • Authentication: Requires valid API key
  • Response: Paginated list of node executions with status, timing, and I/O data

These APIs enable better workflow monitoring, debugging capabilities, and third-party integrations.

New API Endpoints

1. GET /v1/messages/{message_id} - Get Message Detail

Purpose: Retrieve detailed information about a specific message, including workflow run ID and other metadata.

Features:

  • Fetches comprehensive message information by message ID
  • Returns workflow_run_id for workflow-generated messages
  • Includes message status, inputs, outputs, and timing information
  • Supports app token authentication

Implementation: MessageDetailApi class in controllers/service_api/app/message.py

Response Fields:

  • id (string) - Message ID
  • conversation_id (string) - Conversation ID
  • workflow_run_id (string) - Workflow run ID (if message from workflow)
  • inputs (object) - Message input content
  • query (string) - User query content
  • answer (string) - Assistant response content
  • status (string) - Message status
  • created_at (timestamp) - Message creation time
  • Additional metadata fields...

2. GET /v1/node-executions - Get Node Execution List

Purpose: Retrieve detailed execution information for all nodes in a workflow run.

Features:

  • Fetches node execution details by workflow_run_id parameter
  • Returns comprehensive execution data including status, timing, and I/O
  • Supports monitoring workflow execution progress
  • Includes error information for failed nodes

Implementation: NodeExecutionsApi class in controllers/service_api/app/node_executions.py

Query Parameters:

  • workflow_run_id (required) - Workflow run ID to query

Response Fields:

  • id (string) - Node execution ID
  • node_id (string) - Node ID
  • node_type (string) - Node type (e.g., "start", "llm", etc.)
  • title (string) - Node name/title
  • index (int) - Execution sequence number
  • predecessor_node_id (string) - Previous node ID
  • inputs (object) - Node input data
  • outputs (object) - Node output data
  • status (string) - Execution status (running/succeeded/failed/stopped)
  • error (string) - Error message (if failed)
  • elapsed_time (float) - Execution time in seconds
  • execution_metadata (object) - Additional execution metadata
  • created_at (timestamp) - Execution start time
  • finished_at (timestamp) - Execution end time

Technical Implementation Details

Message Detail API

  • File: api/controllers/service_api/app/message.py
  • Class: MessageDetailApi
  • Route: /messages/<uuid:message_id>
  • Authentication: App token validation via @validate_app_token
  • Database Query: Direct query to Message table with app_id filtering
  • Error Handling: Returns 404 for non-existent messages

Node Executions API

  • File: api/controllers/service_api/app/node_executions.py
  • Class: NodeExecutionsApi
  • Route: /node-executions
  • Authentication: App token validation via @validate_app_token
  • Service Integration: Uses WorkflowRunService.get_workflow_run_node_executions()
  • Error Handling: Custom AppUnavailableError for service exceptions

Code Quality Improvements

  • Removed unused Flask imports from service API modules
  • Standardized import statement formatting
  • Enhanced code readability and maintainability
  • Updated service API routing to include new endpoints

Integration Points

Service API Registration

Both new endpoints are properly registered in the service API routing system:

# In controllers/service_api/__init__.py
from .app import (
    # ... existing imports
    node_executions,  # New import
    # ... other imports
)

# In controllers/service_api/app/message.py
api.add_resource(MessageDetailApi, "/messages/<uuid:message_id>")

# In controllers/service_api/app/node_executions.py
api.add_resource(NodeExecutionsApi, "/node-executions")

Workflow Integration

The node executions API integrates with existing workflow infrastructure:

  • Leverages WorkflowRunService for data retrieval
  • Maintains consistency with existing workflow data models
  • Supports all workflow node types and execution states

Usage Examples

Get Message Detail

curl --location --request GET 'https://api.dify.ai/v1/messages/{message_id}' \
--header 'Authorization: Bearer {api_key}'

Get Node Executions

curl --location --request GET 'https://api.dify.ai/v1/node-executions?workflow_run_id={workflow_run_id}' \
--header 'Authorization: Bearer {api_key}'

Benefits

  1. Enhanced Workflow Monitoring: Developers can now track detailed execution progress of workflow nodes
  2. Improved Message Management: Access to comprehensive message metadata including workflow associations
  3. Better Debugging: Detailed error information and execution timing for troubleshooting
  4. API Consistency: Both endpoints follow established service API patterns and authentication
  5. External Integration: Enables third-party applications to monitor and analyze workflow executions

Files Modified

  • api/controllers/service_api/app/node_executions.py (new file)
  • api/controllers/service_api/app/message.py (enhanced MessageDetailApi)
  • api/controllers/service_api/__init__.py (added node_executions import)
  • Various service API files (import cleanup)

Screenshots

Before After
No Service API endpoints for message details and node executions Two new comprehensive API endpoints available for workflow monitoring and message management

Checklist

  • This change requires a documentation update, included: https://github.com/langgenius/dify-docs
  • I understand that this PR may be closed in case there was no previous discussion or issues. (This doesn't apply to typos!)
  • I've added a test for each change that was introduced, and I tried as much as possible to make a single atomic change.
  • I've updated the documentation accordingly.
  • I ran dev/reformat(backend) and cd web && npx lint-staged(frontend) to appease the lint gods
**Original Pull Request:** https://github.com/langgenius/dify/pull/23700 **State:** open **Merged:** No --- > [!IMPORTANT] > > 1. Make sure you have read our [CONTRIBUTING.md](https://github.com/langgenius/dify/blob/main/CONTRIBUTING.md) > 2. Ensure there is an associated issue and you have been assigned to it > 3. Use the correct syntax to link this PR: `Fixes add API node-executions #23677` Fixes add API node-executions close #23677 ## Summary This PR introduces two new Service API endpoints to enhance workflow monitoring and message management capabilities: 1. **Message Details API** (`GET /v1/messages/{message_id}`) - Retrieve comprehensive message information by message ID 2. **Node Executions API** (`GET /v1/node-executions`) - Get workflow run node execution list with detailed execution information Additionally, this PR includes code quality improvements by removing unused Flask imports and formatting import statements. ### Key Changes: - Added `MessageDetailApi` class in `api/controllers/service_api/app/message.py` - Added `NodeExecutionsApi` class in `api/controllers/service_api/app/node_executions.py` - Registered new API endpoints in service API routing - Removed unused Flask imports from service API modules - Applied consistent code formatting ### API Endpoints Added: #### 1. GET /v1/messages/{message_id} - **Purpose**: Fetch detailed message information including content, metadata, and execution context - **Authentication**: Requires valid API key - **Response**: Complete message object with timestamps, token counts, and source information #### 2. GET /v1/node-executions - **Purpose**: Retrieve workflow node execution details for monitoring and debugging - **Parameters**: `workflow_run_id` (required), `limit`, `offset` - **Authentication**: Requires valid API key - **Response**: Paginated list of node executions with status, timing, and I/O data These APIs enable better workflow monitoring, debugging capabilities, and third-party integrations. ## New API Endpoints ### 1. GET /v1/messages/{message_id} - Get Message Detail **Purpose**: Retrieve detailed information about a specific message, including workflow run ID and other metadata. **Features**: - Fetches comprehensive message information by message ID - Returns workflow_run_id for workflow-generated messages - Includes message status, inputs, outputs, and timing information - Supports app token authentication **Implementation**: `MessageDetailApi` class in `controllers/service_api/app/message.py` **Response Fields**: - `id` (string) - Message ID - `conversation_id` (string) - Conversation ID - `workflow_run_id` (string) - Workflow run ID (if message from workflow) - `inputs` (object) - Message input content - `query` (string) - User query content - `answer` (string) - Assistant response content - `status` (string) - Message status - `created_at` (timestamp) - Message creation time - Additional metadata fields... ### 2. GET /v1/node-executions - Get Node Execution List **Purpose**: Retrieve detailed execution information for all nodes in a workflow run. **Features**: - Fetches node execution details by workflow_run_id parameter - Returns comprehensive execution data including status, timing, and I/O - Supports monitoring workflow execution progress - Includes error information for failed nodes **Implementation**: `NodeExecutionsApi` class in `controllers/service_api/app/node_executions.py` **Query Parameters**: - `workflow_run_id` (required) - Workflow run ID to query **Response Fields**: - `id` (string) - Node execution ID - `node_id` (string) - Node ID - `node_type` (string) - Node type (e.g., "start", "llm", etc.) - `title` (string) - Node name/title - `index` (int) - Execution sequence number - `predecessor_node_id` (string) - Previous node ID - `inputs` (object) - Node input data - `outputs` (object) - Node output data - `status` (string) - Execution status (running/succeeded/failed/stopped) - `error` (string) - Error message (if failed) - `elapsed_time` (float) - Execution time in seconds - `execution_metadata` (object) - Additional execution metadata - `created_at` (timestamp) - Execution start time - `finished_at` (timestamp) - Execution end time ## Technical Implementation Details ### Message Detail API - **File**: `api/controllers/service_api/app/message.py` - **Class**: `MessageDetailApi` - **Route**: `/messages/<uuid:message_id>` - **Authentication**: App token validation via `@validate_app_token` - **Database Query**: Direct query to Message table with app_id filtering - **Error Handling**: Returns 404 for non-existent messages ### Node Executions API - **File**: `api/controllers/service_api/app/node_executions.py` - **Class**: `NodeExecutionsApi` - **Route**: `/node-executions` - **Authentication**: App token validation via `@validate_app_token` - **Service Integration**: Uses `WorkflowRunService.get_workflow_run_node_executions()` - **Error Handling**: Custom `AppUnavailableError` for service exceptions ### Code Quality Improvements - Removed unused Flask imports from service API modules - Standardized import statement formatting - Enhanced code readability and maintainability - Updated service API routing to include new endpoints ## Integration Points ### Service API Registration Both new endpoints are properly registered in the service API routing system: ```python # In controllers/service_api/__init__.py from .app import ( # ... existing imports node_executions, # New import # ... other imports ) # In controllers/service_api/app/message.py api.add_resource(MessageDetailApi, "/messages/<uuid:message_id>") # In controllers/service_api/app/node_executions.py api.add_resource(NodeExecutionsApi, "/node-executions") ``` ### Workflow Integration The node executions API integrates with existing workflow infrastructure: - Leverages `WorkflowRunService` for data retrieval - Maintains consistency with existing workflow data models - Supports all workflow node types and execution states ## Usage Examples ### Get Message Detail ```bash curl --location --request GET 'https://api.dify.ai/v1/messages/{message_id}' \ --header 'Authorization: Bearer {api_key}' ``` ### Get Node Executions ```bash curl --location --request GET 'https://api.dify.ai/v1/node-executions?workflow_run_id={workflow_run_id}' \ --header 'Authorization: Bearer {api_key}' ``` ## Benefits 1. **Enhanced Workflow Monitoring**: Developers can now track detailed execution progress of workflow nodes 2. **Improved Message Management**: Access to comprehensive message metadata including workflow associations 3. **Better Debugging**: Detailed error information and execution timing for troubleshooting 4. **API Consistency**: Both endpoints follow established service API patterns and authentication 5. **External Integration**: Enables third-party applications to monitor and analyze workflow executions ## Files Modified - `api/controllers/service_api/app/node_executions.py` (new file) - `api/controllers/service_api/app/message.py` (enhanced MessageDetailApi) - `api/controllers/service_api/__init__.py` (added node_executions import) - Various service API files (import cleanup) ## Screenshots | Before | After | |--------|-------| | No Service API endpoints for message details and node executions | Two new comprehensive API endpoints available for workflow monitoring and message management | ## Checklist - [ ] This change requires a documentation update, included: https://github.com/langgenius/dify-docs - [x] I understand that this PR may be closed in case there was no previous discussion or issues. (This doesn't apply to typos!) - [x] I've added a test for each change that was introduced, and I tried as much as possible to make a single atomic change. - [x] I've updated the documentation accordingly. - [x] I ran `dev/reformat`(backend) and `cd web && npx lint-staged`(frontend) to appease the lint gods
yindo added the pull-request label 2026-02-21 20:47:21 -05:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
Knowledge Pipeline
Proposal
WIP
cloud
dependencies
feat:webapp
good first issue
outdated
performance
pull-request
Mirrored from GitHub Pull Request
 python:uv
refactor
size:L
stale
status: accepting prs
status: blocked
status: in discussion
stt & tts
vulnerablity
web
wont-fix
🌊 feat:workflow
🌚 invalid
🐞 bug
👻 feat:rag
💪 enhancement
📚 documentation
🔨 feat:tools
🙋‍♂️ question
🙏 help wanted
🤔 cant-reproduce
🤖 feat:agent
No Label pull-request
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
yindo
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: langgenius/dify#30362
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?