App Service API Routes
Relevant source files
The following files were used as context for generating this wiki page:
- src/app/api/services/app-service/jobs/[id]/route.ts
- src/app/api/services/app-service/jobs/enumerate-tasks-filtered/route.ts
- src/app/api/services/app-service/jobs/summary/route.ts
- src/app/api/services/app-service/jobs/app-summary/route.ts
- src/app/api/services/app-service/jobs/task-summary/route.ts
- src/lib/app-service.ts
- src/lib/jobs/constants.ts
The App Service API Routes provide a centralized interface for managing, monitoring, and submitting computational jobs within the platform. These routes act as a proxy layer between the frontend and the internal BV-BRC App Service, handling authentication, request validation, and data transformation to ensure a consistent "job" terminology while the underlying system uses "tasks".
Sources: src/lib/app-service.ts:13-17, src/app/api/services/app-service/jobs/[id]/route.ts:1-10
Architecture and Core Logic
The system utilizes a client-service pattern where Next.js API routes instantiate an AppService class. This class uses a JSON-RPC client to communicate with the legacy BV-BRC backend.
Authentication Flow
All routes require a valid BV-BRC authentication token, retrieved from the request context using getBvbrcAuthToken(). If the token is missing, the routes return a 401 Unauthorized response.
The diagram shows the standard authentication and communication flow used across all App Service routes.
Sources: src/lib/app-service.ts:20-22, src/app/api/services/app-service/jobs/[id]/route.ts:15-25
Job Enumeration and Filtering
The route /api/services/app-service/jobs/enumerate-tasks-filtered handles complex queries for job lists, supporting pagination, sorting, and application-specific filtering.
Parameter Mapping
The AppService library maps frontend-friendly field names to the specific naming conventions required by the backend RPC methods.
| Frontend Field | Backend (RPC) Field | Description |
|---|---|---|
status | service_status | Current state of the job |
app | application_id | The specific service ID |
completed_time | finish_time | When the job finalized |
include_archived | include_archived: 1 | Boolean flag converted to numeric for RPC |
Sources: src/lib/app-service.ts:80-92, src/app/api/services/app-service/jobs/enumerate-tasks-filtered/route.ts:7-16
Validation Schema
Request bodies for enumeration are validated using Zod to ensure type safety:
- offset: Non-negative integer (default: 0)
- limit: Positive integer up to 1000 (default: 200)
- sort_field: Enums including
submit_time,start_time, andcompleted_time.
Sources: src/app/api/services/app-service/jobs/enumerate-tasks-filtered/route.ts:7-16
Summary and Statistics Routes
The API provides endpoints to retrieve high-level statistics about job counts and application usage.
- Combined Summary:
/api/services/app-service/jobs/summaryperforms parallel requests for both task and app summaries usingPromise.all. - Task Summary: Provides counts based on status (e.g., queued, running, completed).
- App Summary: Provides distribution of jobs across different tools (e.g., Genome Assembly, BLAST).
The flow shows how the summary route aggregates data from multiple backend RPC calls.
Sources: src/app/api/services/app-service/jobs/summary/route.ts:11-30, src/lib/app-service.ts:110-130
Job Life Cycle Management
Detailed Information and Logs
The GET /api/services/app-service/jobs/[id] route retrieves full metadata for a specific job. It accepts an include_logs query parameter which determines if internal logs are returned alongside status data.
Sources: src/app/api/services/app-service/jobs/[id]/route.ts:36-45, src/lib/app-service.ts:31-38
Job Termination (Kill)
Jobs can be terminated via a POST request to /api/services/app-service/jobs/[id]/kill. The implementation ensures the job_id is passed as a Number to the backend RPC AppService.kill_task, returning a boolean success flag and a message.
Sources: src/lib/app-service.ts:43-56
Output Retrieval
The API provides direct access to standard streams via HTTP GET:
.../jobs/[id]/stdout.../jobs/[id]/stderr
Unlike other routes using JSON-RPC, these fetch data via direct HTTP GET requests to https://p3.theseed.org/services/app_service/task_info/ using the OAuth token in the Authorization header.
Sources: src/lib/app-service.ts:64-75
Job Status Constants
The platform uses a standard set of statuses to track job progress. These are mapped to UI components like icons and colors.
| Status | Category | UI Icon |
|---|---|---|
queued, pending | Active | Clock |
running, in-progress | Active | Loader2 (Spinning) |
completed | Terminal | CheckCircle2 |
failed, error | Terminal | XCircle / AlertCircle |
cancelled | Terminal | Ban |
Sources: src/lib/jobs/constants.ts:12-36
Summary
The App Service API Routes form a robust gateway for job management, abstraction, and monitoring. By leveraging the AppService library, these routes handle the translation between modern frontend requirements and legacy backend protocols, ensuring that job submission, status tracking, and log retrieval are handled securely and efficiently.