meldestelle/docs/API_DOCUMENTATION.md

API Documentation - Meldestelle Self-Contained Systems

Overview

This document provides comprehensive documentation for the Meldestelle API Gateway, which aggregates all bounded context APIs into a unified interface while maintaining the independence of each context.

Features Implemented

✅ OpenAPI/Swagger Integration

• OpenAPI 3.0 specification generation
• Swagger UI interactive documentation
• Automatic API documentation from code annotations
• Multiple server environments (development, production)

✅ Postman Collections

• Comprehensive API collection covering all endpoints
• Environment variables for easy configuration
• Authentication token management with automatic token extraction
• Pre-configured request examples for all endpoints

✅ API Tests

• Integration tests for all major endpoints
• Authentication flow testing
• CRUD operation validation
• Error handling verification

API Structure

The API Gateway aggregates the following bounded contexts:

1. System Information

• GET / - API Gateway information
• GET /health - Health check for all contexts
• GET /api - API documentation overview
• GET /swagger - Interactive Swagger UI

2. Authentication Context (/auth/*)

• POST /auth/register - User registration
• POST /auth/login - User authentication
• GET /auth/profile - Get user profile
• PUT /auth/profile - Update user profile
• POST /auth/change-password - Change password

3. Master Data Context (/api/masterdata/*)

• GET /api/masterdata/countries - Get all countries
• GET /api/masterdata/countries/active - Get active countries
• GET /api/masterdata/countries/{id} - Get country by ID
• GET /api/masterdata/countries/iso/{code} - Get country by ISO code
• POST /api/masterdata/countries - Create country
• PUT /api/masterdata/countries/{id} - Update country
• DELETE /api/masterdata/countries/{id} - Delete country

4. Horse Registry Context (/api/horses/*)

• GET /api/horses - Get all horses
• GET /api/horses/active - Get active horses
• GET /api/horses/{id} - Get horse by ID
• GET /api/horses/search - Search horses by name
• GET /api/horses/owner/{ownerId} - Get horses by owner
• POST /api/horses - Create horse
• PUT /api/horses/{id} - Update horse
• DELETE /api/horses/{id} - Delete horse
• DELETE /api/horses/batch - Batch delete horses
• GET /api/horses/stats - Get horse statistics

Getting Started

1. Start the API Gateway

# Navigate to the project root
cd /path/to/meldestelle

# Run the API Gateway
./gradlew :api-gateway:run

The API will be available at http://localhost:8080

2. Access Swagger UI

Open your browser and navigate to:

http://localhost:8080/swagger

This provides an interactive interface to explore and test all API endpoints.

3. Use Postman Collection

1. Import the Postman collection from docs/postman/Meldestelle_API_Collection.json
2. Set the baseUrl variable to http://localhost:8080
3. Start with the "System Information" folder to verify the API is running
4. Use the "Authentication Context" to get an auth token
5. The token will be automatically saved and used for authenticated endpoints

Authentication

The API uses JWT (JSON Web Token) based authentication:

1. Register a new user via POST /auth/register
2. Login with credentials via POST /auth/login
3. Extract the JWT token from the login response
4. Include the token in the Authorization header: Bearer <token>

Example Authentication Flow

# 1. Register a new user
curl -X POST http://localhost:8080/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "password": "SecurePassword123!",
    "firstName": "Test",
    "lastName": "User",
    "phoneNumber": "+43123456789"
  }'

# 2. Login to get token
curl -X POST http://localhost:8080/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "password": "SecurePassword123!"
  }'

# 3. Use token for authenticated requests
curl -X GET http://localhost:8080/api/horses \
  -H "Authorization: Bearer <your-jwt-token>"

Response Format

All API responses follow a consistent format using the BaseDto wrapper:

{
  "success": true,
  "data": {
    "example": "Actual response data goes here"
  },
  "message": "Operation completed successfully",
  "timestamp": "2024-01-15T10:30:00Z"
}

Error Response Format

{
  "success": false,
  "data": null,
  "message": "Error description",
  "errors": [
    {
      "field": "email",
      "message": "Invalid email format"
    }
  ],
  "timestamp": "2024-01-15T10:30:00Z"
}

Testing

Running API Tests

# Run all API Gateway tests
./gradlew :api-gateway:test

# Run specific test class
./gradlew :api-gateway:test --tests "ApiIntegrationTest"

# Run with verbose output
./gradlew :api-gateway:test --info

Test Coverage

The test suite covers:

• ✅ API Gateway information endpoints
• ✅ Health check functionality
• ✅ OpenAPI/Swagger integration
• ✅ Authentication endpoints structure
• ✅ Master data CRUD operations
• ✅ Horse registry endpoints
• ✅ Error handling and validation
• ✅ CORS configuration
• ✅ Content negotiation

Development

Adding New Endpoints

1. Create the endpoint in the appropriate controller
2. Add route configuration in RoutingConfig.kt
3. Update Postman collection with new requests
4. Add integration tests for the new functionality
5. Update this documentation

OpenAPI Annotations

Use OpenAPI annotations to enhance documentation:

@OpenAPITag(name = "Horses", description = "Horse registry operations")
fun Route.horseRoutes() {
    route("/api/horses") {
        @OpenAPIResponse("200", [OpenAPIContent(HorseDto::class)])
        @OpenAPIResponse("404", [OpenAPIContent(ErrorDto::class)])
        get {
            // Implementation
        }
    }
}

Configuration

Environment Variables

Variable	Description	Default
SERVER_PORT	API Gateway port	8080
DATABASE_URL	Database connection URL	jdbc:h2:mem:test
JWT_SECRET	JWT signing secret	Generated
CORS_ORIGINS	Allowed CORS origins	*

Application Configuration

The API Gateway can be configured via application.conf:

ktor {
    application {
        modules = [ at.mocode.gateway.ApplicationKt.module ]
    }

    deployment {
        port = 8080
        port = ${?SERVER_PORT}
    }
}

database {
    url = "jdbc:h2:mem:test"
    url = ${?DATABASE_URL}
    user = "sa"
    password = ""
}

Monitoring and Logging

Health Checks

The /health endpoint provides status information for all bounded contexts:

{
  "success": true,
  "data": {
    "status": "UP",
    "contexts": {
      "authentication": "UP",
      "master-data": "UP",
      "horse-registry": "UP"
    }
  }
}

Logging

The API Gateway uses structured logging with the following levels:

• ERROR - System errors and exceptions
• WARN - Business logic warnings
• INFO - Request/response logging
• DEBUG - Detailed debugging information

Security

Authentication & Authorization

• JWT-based authentication for stateless security
• Role-based access control (RBAC) for fine-grained permissions
• Password hashing using bcrypt
• Token expiration and refresh mechanisms

CORS Configuration

Cross-Origin Resource Sharing (CORS) is configured to allow:

• Specific origins for production environments
• All HTTP methods (GET, POST, PUT, DELETE, OPTIONS)
• Custom headers including Authorization

Input Validation

All API endpoints implement:

• Request body validation using Kotlin serialization
• Parameter validation for path and query parameters
• Business rule validation in use case layers
• SQL injection prevention through parameterized queries

Troubleshooting

Common Issues

1. Port already in use

   # Check what's using port 8080
   lsof -i :8080
   # Kill the process or use a different port
   SERVER_PORT=8081 ./gradlew :api-gateway:run
   

2. Database connection issues

   # Check database configuration
   # Verify connection string and credentials
   # Ensure database server is running
   

3. Authentication failures

   # Verify JWT token is valid and not expired
   # Check Authorization header format: "Bearer <token>"
   # Ensure user has required permissions
   

Debug Mode

Enable debug logging for troubleshooting:

# Run with debug logging
./gradlew :api-gateway:run --debug

# Or set log level in application.conf
logger.level = DEBUG

Contributing

When contributing to the API:

1. Follow REST conventions for endpoint design
2. Maintain backward compatibility when possible
3. Update documentation for any API changes
4. Add comprehensive tests for new functionality
5. Use consistent error handling patterns

Support

For API support and questions:

• Documentation: This file and Swagger UI
• Issues: Create GitHub issues for bugs
• Testing: Use Postman collection for manual testing
• Monitoring: Check /health endpoint for system status