103 lines
2.8 KiB
Markdown
103 lines
2.8 KiB
Markdown
# Endpoint Structure Pattern
|
|
|
|
This document describes the Endpoint Structure pattern used in the EVYOS backend services.
|
|
|
|
## Overview
|
|
|
|
The Endpoint Structure is a modular, event-driven architecture pattern that provides clear separation of concerns for API services. It consists of three main components:
|
|
|
|
1. **Events Component**
|
|
2. **Endpoints Component**
|
|
3. **Validations Component**
|
|
|
|
This architecture enables scalable, maintainable API services with a consistent structure.
|
|
|
|
## Directory Structure
|
|
|
|
```
|
|
ApiServices/
|
|
└── [ServiceName]/
|
|
├── Events/
|
|
│ └── [entity]/
|
|
│ ├── cluster.py
|
|
│ └── supers_events.py
|
|
├── Endpoints/
|
|
│ └── [entity]/
|
|
│ └── route.py
|
|
└── Validations/
|
|
└── [entity]/
|
|
└── [entity]/
|
|
└── validations.py
|
|
```
|
|
|
|
## Components
|
|
|
|
### 1. Events Component
|
|
|
|
Located at `ApiServices/[ServiceName]/Events/[entity]/`
|
|
|
|
#### cluster.py
|
|
- Organizes events into clusters for routing
|
|
- Contains:
|
|
- `RouterCluster`: Top-level container for event clusters
|
|
- `EventCluster`: Groups related events (List, Create, Update)
|
|
- Each cluster has a unique name and UUID
|
|
|
|
#### supers_events.py
|
|
- Defines event handlers with business logic
|
|
- Contains:
|
|
- `Event` objects with unique name, key, validators, and description
|
|
- Callable methods implementing business logic
|
|
- Events are registered to their respective clusters
|
|
|
|
### 2. Endpoints Component
|
|
|
|
Located at `ApiServices/[ServiceName]/Endpoints/[entity]/`
|
|
|
|
#### route.py
|
|
- Defines FastAPI routes that map to event handlers
|
|
- Contains:
|
|
- APIRouter with prefix and tags
|
|
- Route functions that:
|
|
- Extract token information
|
|
- Retrieve event codes
|
|
- Match to appropriate event cluster
|
|
- Call corresponding event handler
|
|
|
|
### 3. Validations Component
|
|
|
|
Located at `ApiServices/[ServiceName]/Validations/[entity]/[entity]/`
|
|
|
|
#### validations.py
|
|
- Defines Pydantic models for request/response validation
|
|
- Contains:
|
|
- Request models with field definitions
|
|
- Response models for structured responses
|
|
|
|
## Data Flow
|
|
|
|
1. Request → FastAPI endpoint
|
|
2. Data validation with Pydantic
|
|
3. Token extraction and event code retrieval
|
|
4. Event matching and handler execution
|
|
5. Business logic execution
|
|
6. Formatted response return
|
|
|
|
## Implementation Guide
|
|
|
|
To implement a new endpoint using this structure:
|
|
|
|
1. Create the directory structure for your entity
|
|
2. Define validation models in `validations.py`
|
|
3. Create events and their callable methods in `supers_events.py`
|
|
4. Organize events into clusters in `cluster.py`
|
|
5. Define API routes in `route.py`
|
|
|
|
## Benefits
|
|
|
|
- Clear separation of concerns
|
|
- Consistent structure across services
|
|
- Scalable and maintainable architecture
|
|
- Flexible event-driven design
|
|
- Standardized response format
|