(fix) API Endpoints Creation for All Tables
This commit is contained in:
@@ -0,0 +1,224 @@
|
||||
# Code Organization Improvements
|
||||
|
||||
This document describes the recent reorganization of the codebase to improve maintainability, extensibility, and clarity.
|
||||
|
||||
## Overview
|
||||
|
||||
The codebase has been restructured to follow better software engineering practices, making it more organized, maintainable, and easier to extend.
|
||||
|
||||
## Key Improvements
|
||||
|
||||
### 1. Service Locator Pattern (`ServiceLocator.kt`)
|
||||
|
||||
**Location**: `server/src/main/kotlin/at/mocode/services/ServiceLocator.kt`
|
||||
|
||||
**Purpose**: Centralized dependency management for repository instances.
|
||||
|
||||
**Benefits**:
|
||||
- Single point of access for all repositories
|
||||
- Easy to switch implementations (e.g., for testing or different databases)
|
||||
- Lazy initialization for better performance
|
||||
- Simplified dependency injection
|
||||
|
||||
**Usage**:
|
||||
```kotlin
|
||||
val artikelRepository = ServiceLocator.artikelRepository
|
||||
val vereinRepository = ServiceLocator.vereinRepository
|
||||
```
|
||||
|
||||
### 2. Standardized API Responses (`ApiResponse.kt`)
|
||||
|
||||
**Location**: `server/src/main/kotlin/at/mocode/utils/ApiResponse.kt`
|
||||
|
||||
**Purpose**: Consistent response format across all API endpoints.
|
||||
|
||||
**Benefits**:
|
||||
- Uniform error handling
|
||||
- Standardized success/error response structure
|
||||
- Reduced code duplication
|
||||
- Better client-side error handling
|
||||
|
||||
**Usage**:
|
||||
```kotlin
|
||||
call.respondSuccess(data)
|
||||
call.respondError("Error message")
|
||||
call.respondNotFound("Resource")
|
||||
```
|
||||
|
||||
### 3. Route Utilities (`RouteUtils.kt`)
|
||||
|
||||
**Location**: `server/src/main/kotlin/at/mocode/utils/RouteUtils.kt`
|
||||
|
||||
**Purpose**: Common route operations and parameter validation.
|
||||
|
||||
**Benefits**:
|
||||
- Consistent parameter validation
|
||||
- Reduced boilerplate code
|
||||
- Standardized error responses
|
||||
- Type-safe parameter extraction
|
||||
|
||||
**Usage**:
|
||||
```kotlin
|
||||
val uuid = call.getUuidParameter("id", "artikel") ?: return
|
||||
val query = call.getQueryParameter("q") ?: return
|
||||
val data = call.safeReceive<Artikel>() ?: return
|
||||
```
|
||||
|
||||
### 4. Centralized Route Configuration (`RouteConfiguration.kt`)
|
||||
|
||||
**Location**: `server/src/main/kotlin/at/mocode/routes/RouteConfiguration.kt`
|
||||
|
||||
**Purpose**: Organized route registration by domain and functionality.
|
||||
|
||||
**Benefits**:
|
||||
- Clear API structure
|
||||
- Logical grouping of related endpoints
|
||||
- Easy to understand and maintain
|
||||
- Scalable for future additions
|
||||
|
||||
**Structure**:
|
||||
```
|
||||
/api
|
||||
├── /artikel (core routes)
|
||||
├── /personen
|
||||
├── /vereine
|
||||
├── /domain
|
||||
│ ├── /lizenzen
|
||||
│ ├── /pferde
|
||||
│ └── /qualifikationen
|
||||
└── /events
|
||||
├── /veranstaltungen
|
||||
├── /turniere
|
||||
├── /bewerbe
|
||||
└── /abteilungen
|
||||
```
|
||||
|
||||
### 5. Configuration Management (`AppConfig.kt`)
|
||||
|
||||
**Location**: `server/src/main/kotlin/at/mocode/config/AppConfig.kt`
|
||||
|
||||
**Purpose**: Centralized application configuration management.
|
||||
|
||||
**Benefits**:
|
||||
- Environment-specific settings
|
||||
- Type-safe configuration
|
||||
- Default values for development
|
||||
- Easy to extend for new settings
|
||||
|
||||
**Features**:
|
||||
- Application info (name, version, environment)
|
||||
- Database configuration
|
||||
- API settings
|
||||
- Security configuration
|
||||
|
||||
## Migration Guide
|
||||
|
||||
### For Existing Routes
|
||||
|
||||
1. **Update Repository Access**:
|
||||
```kotlin
|
||||
// Before
|
||||
val repository = PostgresArtikelRepository()
|
||||
|
||||
// After
|
||||
val repository = ServiceLocator.artikelRepository
|
||||
```
|
||||
|
||||
2. **Update Route Paths**:
|
||||
```kotlin
|
||||
// Before
|
||||
route("/api/artikel") { ... }
|
||||
|
||||
// After
|
||||
route("/artikel") { ... } // /api prefix handled by RouteConfiguration
|
||||
```
|
||||
|
||||
3. **Use Response Utilities**:
|
||||
```kotlin
|
||||
// Before
|
||||
call.respond(HttpStatusCode.OK, data)
|
||||
|
||||
// After
|
||||
call.respondSuccess(data)
|
||||
```
|
||||
|
||||
4. **Use Route Utilities**:
|
||||
```kotlin
|
||||
// Before
|
||||
val id = call.parameters["id"] ?: return@get call.respond(...)
|
||||
val uuid = uuidFrom(id)
|
||||
|
||||
// After
|
||||
val uuid = call.getUuidParameter("id") ?: return
|
||||
```
|
||||
|
||||
### For New Routes
|
||||
|
||||
1. Add repository interface to `ServiceLocator`
|
||||
2. Create route function using utilities
|
||||
3. Register in appropriate section of `RouteConfiguration`
|
||||
4. Update route paths to exclude `/api` prefix
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Repository Pattern
|
||||
- Always use interfaces for repositories
|
||||
- Implement PostgreSQL versions for production
|
||||
- Use ServiceLocator for dependency injection
|
||||
|
||||
### Error Handling
|
||||
- Use ResponseUtils for consistent error responses
|
||||
- Handle common exceptions with `handleException()`
|
||||
- Provide meaningful error messages
|
||||
|
||||
### Route Organization
|
||||
- Group related routes logically
|
||||
- Use descriptive route names
|
||||
- Follow RESTful conventions
|
||||
- Document complex endpoints
|
||||
|
||||
### Configuration
|
||||
- Use AppConfig for all settings
|
||||
- Provide sensible defaults
|
||||
- Support environment-specific overrides
|
||||
- Keep sensitive data in environment variables
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### Planned Improvements
|
||||
1. **Authentication & Authorization**
|
||||
- JWT token support
|
||||
- Role-based access control
|
||||
- Session management
|
||||
|
||||
2. **API Documentation**
|
||||
- OpenAPI/Swagger integration
|
||||
- Automatic documentation generation
|
||||
- Interactive API explorer
|
||||
|
||||
3. **Monitoring & Logging**
|
||||
- Structured logging
|
||||
- Performance metrics
|
||||
- Health checks
|
||||
|
||||
4. **Testing Framework**
|
||||
- Unit test utilities
|
||||
- Integration test helpers
|
||||
- Mock repository implementations
|
||||
|
||||
### Extension Points
|
||||
- Add new repositories to ServiceLocator
|
||||
- Extend RouteConfiguration for new domains
|
||||
- Add configuration sections to AppConfig
|
||||
- Create new utility functions as needed
|
||||
|
||||
## Benefits Summary
|
||||
|
||||
1. **Maintainability**: Clear separation of concerns and consistent patterns
|
||||
2. **Extensibility**: Easy to add new features and endpoints
|
||||
3. **Testability**: Dependency injection and clear interfaces
|
||||
4. **Consistency**: Standardized responses and error handling
|
||||
5. **Documentation**: Self-documenting code structure
|
||||
6. **Performance**: Lazy loading and efficient resource management
|
||||
|
||||
This reorganization provides a solid foundation for future development while maintaining backward compatibility and improving code quality.
|
||||
Reference in New Issue
Block a user