# Meldestelle API Documentation

# Meldestelle Self-Contained Systems API

Unified API Gateway for all bounded contexts of the Austrian Equestrian Federation's Meldestelle system.

Interactive API Documentation OpenAPI Specification

## Overview

The Meldestelle API provides a unified interface to various bounded contexts while maintaining the independence of each context. This API Gateway aggregates all bounded context APIs and provides a single entry point for clients.

The API follows REST principles and uses JSON for data exchange. All responses are wrapped in a consistent format using the `BaseDto` wrapper.

Authentication is handled using JWT (JSON Web Token) based authentication. Most endpoints require authentication, which can be obtained by registering and logging in through the Authentication Context.

## API Contexts

### Authentication Context

User authentication, registration, and profile management

Base Path: /auth

#### Key Endpoints:

- 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

### Members Context

Member registration, profile management, and membership administration

Base Path: /api/members

#### Key Endpoints:

- GET /api/members - Get all members with pagination
- GET /api/members/search - Search members by criteria
- GET /api/members/{id} - Get member by ID
- POST /api/members - Create new member
- PUT /api/members/{id} - Update member information
- DELETE /api/members/{id} - Delete member (soft delete)

### Master Data Context

Reference data management (countries, states, age classes, venues)

Base Path: /api/masterdata

#### Key Endpoints:

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

### Horse Registry Context

Horse registration, ownership, and pedigree management

Base Path: /api/horses

#### Key Endpoints:

- 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
- POST /api/horses - Create horse
- PUT /api/horses/{id} - Update horse
- DELETE /api/horses/{id} - Delete horse

### Event Management Context

Event creation, management, and participant registration

Base Path: /api/events

#### Key Endpoints:

- GET /api/events - Get all events
- GET /api/events/stats - Get event statistics
- POST /api/events - Create event
- GET /api/events/{id} - Get event by ID
- PUT /api/events/{id} - Update event
- DELETE /api/events/{id} - Delete event
- GET /api/events/search - Search events

## Documentation Resources

### Swagger UI

Interactive documentation for exploring and testing the API endpoints.

Open Swagger UI

### OpenAPI Specification

Raw OpenAPI 3.0.3 specification in YAML format for code generation or import into other tools.

View OpenAPI Spec

### Postman Collection

Comprehensive API collection covering all endpoints with pre-configured request examples.

Download Collection

### Health Monitoring

Real-time health status and monitoring information for all downstream services.

View Health Status

## System Monitoring & Health

### Health Check Endpoints

The API Gateway provides comprehensive health monitoring for all downstream services:

#### Monitoring Endpoints:

- GET /actuator/health - Comprehensive health status of all services
- GET /actuator/metrics - System metrics and performance data
- GET /actuator/info - Application information and build details
- GET /actuator/prometheus - Prometheus-compatible metrics export

Health Indicator Features:

- Monitors critical services: Members, Horses, Events, Masterdata, Auth
- Optional service monitoring: Ping service
- Circuit breaker status integration
- Service discovery status from Consul
- Detailed error reporting and status codes

## Getting Started

### 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>`

### 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"
    }