REST API Server

Relevant source files

The following files were used as context for generating this wiki page:

• apps/api/src/api/mod.rs
• apps/api/src/api/dto.rs
• apps/api/AGENTS.md
• DOCUMENTATION.md
• specs/tech/project-wiki.md

The REST API Server serves as the primary interface for client applications to interact with the Atmos system. It provides structured endpoints for managing projects, workspaces, and system configurations. The server is designed with a layered architecture, separating request handling, data transfer objects (DTOs), and core business logic to ensure maintainability and scalability.

Within the broader project architecture, the API server acts as the bridge between the frontend applications (such as the web dashboard) and the underlying infrastructure services. It handles authentication, validates incoming requests through standardized DTOs, and orchestrates operations across the workspace and file system layers.

Sources: apps/api/AGENTS.md, DOCUMENTATION.md

Architecture and Design

The API server follows a modular design pattern where routes and handlers are defined within specific modules. The system utilizes a centralized routing configuration to manage public and protected resources.

Request Handling Flow

When a request reaches the API server, it undergoes a series of transformations and validations. The following diagram illustrates the lifecycle of an API request:

The router directs traffic to specific handlers based on the URI path and HTTP method. Handlers utilize Data Transfer Objects (DTOs) to deserialize and validate incoming JSON payloads before passing data to the service layer.

Sources: apps/api/src/api/mod.rs, apps/api/src/api/dto.rs

Data Transfer Objects (DTOs)

The API relies on structured DTOs to define the shape of requests and responses. These structures ensure type safety and consistent data formats across the network boundary.

Workspace and Project Models

DTOs are categorized by their functional domain, such as project management or terminal orchestration.

DTO Name	Purpose	Fields
ProjectDTO	Represents project metadata	id, name, localPath, mainFilePath
WorkspaceDTO	Represents a development workspace	id, name, localPath, projectId
TerminalCommandDTO	Payload for terminal execution	command, paneId

Sources: apps/api/src/api/dto.rs, specs/tech/project-wiki.md

Example: Project DTO Structure

// Representative structure of a Project Data Transfer Object
pub struct ProjectDto {
    pub id: String,
    pub name: String,
    pub local_path: String,
    pub main_file_path: Option<String>,
}

Sources: apps/api/src/api/dto.rs

API Endpoints and Routing

Routing is handled programmatically, allowing for the grouping of related functionalities. The server distinguishes between standard RESTful HTTP endpoints and real-time communication channels like WebSockets.

REST Endpoints Summary

Method	Endpoint	Description
GET	/api/projects	List all available projects
POST	/api/projects	Create a new project entry
GET	/api/workspaces	List active workspaces
POST	/api/terminal/run	Execute a command in a terminal pane

Sources: apps/api/src/api/mod.rs, specs/tech/project-wiki.md

Integration with Frontend

The frontend integrates with the REST API using a WebSocket-backed or standard fetch-based approach depending on the operation's nature. For instance, file system operations utilize the fsApi which communicates with the backend to read or write files.

Development and Maintenance

The API server is located within the apps/api directory. Developers working on the API are expected to follow specific workflows for adding new routes or updating existing DTOs.

Workflow for Adding Endpoints

1. Define DTOs: Update src/api/dto.rs with necessary request/response structures.
2. Implement Handler: Create or update logic in the relevant module.
3. Register Route: Add the handler to the router in src/api/mod.rs.
4. Update Specs: Refine specs/tech/ documentation to reflect API changes.

Sources: apps/api/AGENTS.md, DOCUMENTATION.md

Conclusion

The REST API Server is a critical component of the Atmos ecosystem, providing the structured interface necessary for managing complex workspace and project lifecycles. By utilizing strict DTO validation and a modular routing architecture, it ensures secure and predictable communication between the client-side UI and the server-side infrastructure.