meldestelle/docs/API_Documentation.md

Meldestelle RESTful API Documentation

Overview

This document describes the RESTful API for the Meldestelle (Austrian Equestrian Event Management System). The API provides endpoints for managing persons, clubs (Vereine), articles (Artikel), horses (Pferde), and tournaments (Turniere).

Base URL

http://localhost:8080

Authentication

Currently, the API does not implement authentication. This should be added in production.

Content Type

All requests and responses use application/json content type.

Error Handling

All endpoints return consistent error responses:

{
  "error": "Error message description"
}

HTTP Status Codes

• 200 OK - Successful GET/PUT requests
• 201 Created - Successful POST requests
• 204 No Content - Successful DELETE requests
• 400 Bad Request - Invalid request parameters or body
• 404 Not Found - Resource not found
• 500 Internal Server Error - Server error

---

Health Check

GET /health

Returns server health status.

Response:

OK

---

Persons API

GET /api/persons

Get all persons.

Response:

[
  {
    "id": "uuid",
    "oepsSatzNr": "string",
    "nachname": "string",
    "vorname": "string",
    "titel": "string",
    "geburtsdatum": "2023-01-01",
    "geschlechtE": "MAENNLICH|WEIBLICH|DIVERS",
    "nationalitaet": "AUT",
    "email": "string",
    "telefon": "string",
    "adresse": "string",
    "plz": "string",
    "ort": "string",
    "stammVereinId": "uuid",
    "mitgliedsNummerIntern": "string",
    "letzteZahlungJahr": 2023,
    "feiId": "string",
    "istGesperrt": false,
    "sperrGrund": "string",
    "rollen": ["REITER", "RICHTER"],
    "lizenzen": [],
    "qualifikationenRichter": ["string"],
    "qualifikationenParcoursbauer": ["string"],
    "istAktiv": true,
    "createdAt": "2023-01-01T00:00:00Z",
    "updatedAt": "2023-01-01T00:00:00Z"
  }
]

GET /api/persons/{id}

Get person by ID.

Parameters:

• id (path) - UUID of the person

GET /api/persons/oeps/{oepsSatzNr}

Get person by OEPS registration number.

Parameters:

• oepsSatzNr (path) - OEPS registration number

GET /api/persons/search?q={query}

Search persons by name or email.

Parameters:

• q (query) - Search query string

GET /api/persons/verein/{vereinId}

Get all persons belonging to a specific club.

Parameters:

• vereinId (path) - UUID of the club

POST /api/persons

Create a new person.

Request Body:

{
  "oepsSatzNr": "string",
  "nachname": "string",
  "vorname": "string",
  "titel": "string",
  "geburtsdatum": "2023-01-01",
  "geschlechtE": "MAENNLICH",
  "nationalitaet": "AUT",
  "email": "string",
  "telefon": "string",
  "adresse": "string",
  "plz": "string",
  "ort": "string",
  "stammVereinId": "uuid",
  "istAktiv": true
}

PUT /api/persons/{id}

Update an existing person.

Parameters:

• id (path) - UUID of the person

Request Body: Same as POST

DELETE /api/persons/{id}

Delete a person.

Parameters:

• id (path) - UUID of the person

---

Clubs (Vereine) API

GET /api/vereine

Get all clubs.

Response:

[
  {
    "id": "uuid",
    "oepsVereinsNr": "string",
    "name": "string",
    "kuerzel": "string",
    "bundesland": "string",
    "adresse": "string",
    "plz": "string",
    "ort": "string",
    "email": "string",
    "telefon": "string",
    "webseite": "string",
    "istAktiv": true,
    "createdAt": "2023-01-01T00:00:00Z",
    "updatedAt": "2023-01-01T00:00:00Z"
  }
]

GET /api/vereine/{id}

Get club by ID.

Parameters:

• id (path) - UUID of the club

GET /api/vereine/oeps/{oepsVereinsNr}

Get club by OEPS club number.

Parameters:

• oepsVereinsNr (path) - OEPS club number

GET /api/vereine/search?q={query}

Search clubs by name, abbreviation, or location.

Parameters:

• q (query) - Search query string

GET /api/vereine/bundesland/{bundesland}

Get clubs by federal state.

Parameters:

• bundesland (path) - Federal state code

POST /api/vereine

Create a new club.

Request Body:

{
  "oepsVereinsNr": "string",
  "name": "string",
  "kuerzel": "string",
  "bundesland": "string",
  "adresse": "string",
  "plz": "string",
  "ort": "string",
  "email": "string",
  "telefon": "string",
  "webseite": "string",
  "istAktiv": true
}

PUT /api/vereine/{id}

Update an existing club.

Parameters:

• id (path) - UUID of the club

Request Body: Same as POST

DELETE /api/vereine/{id}

Delete a club.

Parameters:

• id (path) - UUID of the club

---

Articles (Artikel) API

GET /api/artikel

Get all articles.

Response:

[
  {
    "id": "uuid",
    "bezeichnung": "string",
    "preis": "10.50",
    "einheit": "string",
    "istVerbandsabgabe": false,
    "createdAt": "2023-01-01T00:00:00Z",
    "updatedAt": "2023-01-01T00:00:00Z"
  }
]

GET /api/artikel/{id}

Get article by ID.

Parameters:

• id (path) - UUID of the article

GET /api/artikel/search?q={query}

Search articles by name or unit.

Parameters:

• q (query) - Search query string

GET /api/artikel/verbandsabgabe/{istVerbandsabgabe}

Get articles by association fee status.

Parameters:

• istVerbandsabgabe (path) - Boolean value (true/false)

POST /api/artikel

Create a new article.

Request Body:

{
  "bezeichnung": "string",
  "preis": "10.50",
  "einheit": "string",
  "istVerbandsabgabe": false
}

PUT /api/artikel/{id}

Update an existing article.

Parameters:

• id (path) - UUID of the article

Request Body: Same as POST

DELETE /api/artikel/{id}

Delete an article.

Parameters:

• id (path) - UUID of the article

---

Horses (Pferde) API

GET /api/horses

Get all horses.

Response:

[
  {
    "pferdId": "uuid",
    "oepsSatzNrPferd": "string",
    "oepsKopfNr": "string",
    "name": "string",
    "lebensnummer": "string",
    "feiPassNr": "string",
    "geburtsjahr": 2015,
    "geschlecht": "WALLACH|STUTE|HENGST",
    "farbe": "string",
    "rasse": "string",
    "abstammungVaterName": "string",
    "abstammungMutterName": "string",
    "abstammungMutterVaterName": "string",
    "abstammungZusatzInfo": "string",
    "besitzerPersonId": "uuid",
    "verantwortlichePersonId": "uuid",
    "heimatVereinId": "uuid",
    "letzteZahlungPferdegebuehrJahrOeps": 2023,
    "stockmassCm": 165,
    "datenQuelle": "MANUELL|ZNS_IMPORT",
    "istAktiv": true,
    "notizenIntern": "string",
    "createdAt": "2023-01-01T00:00:00Z",
    "updatedAt": "2023-01-01T00:00:00Z"
  }
]

GET /api/horses/{id}

Get horse by ID.

Parameters:

• id (path) - UUID of the horse

GET /api/horses/oeps/{oepsSatzNr}

Get horse by OEPS registration number.

Parameters:

• oepsSatzNr (path) - OEPS registration number

GET /api/horses/lebensnummer/{lebensnummer}

Get horse by life number (UELN).

Parameters:

• lebensnummer (path) - Horse life number

GET /api/horses/search?q={query}

Search horses by name or other attributes.

Parameters:

• q (query) - Search query string

GET /api/horses/name/{name}

Get horses by name.

Parameters:

• name (path) - Horse name

GET /api/horses/owner/{ownerId}

Get horses by owner ID.

Parameters:

• ownerId (path) - UUID of the owner person

GET /api/horses/responsible/{personId}

Get horses by responsible person ID.

Parameters:

• personId (path) - UUID of the responsible person

GET /api/horses/club/{clubId}

Get horses by home club ID.

Parameters:

• clubId (path) - UUID of the home club

GET /api/horses/breed/{breed}

Get horses by breed.

Parameters:

• breed (path) - Horse breed

GET /api/horses/birth-year/{year}

Get horses by birth year.

Parameters:

• year (path) - Birth year (integer)

GET /api/horses/active

Get only active horses.

POST /api/horses

Create a new horse.

Request Body:

{
  "oepsSatzNrPferd": "string",
  "oepsKopfNr": "string",
  "name": "string",
  "lebensnummer": "string",
  "feiPassNr": "string",
  "geburtsjahr": 2015,
  "geschlecht": "WALLACH",
  "farbe": "string",
  "rasse": "string",
  "abstammungVaterName": "string",
  "abstammungMutterName": "string",
  "abstammungMutterVaterName": "string",
  "abstammungZusatzInfo": "string",
  "besitzerPersonId": "uuid",
  "verantwortlichePersonId": "uuid",
  "heimatVereinId": "uuid",
  "letzteZahlungPferdegebuehrJahrOeps": 2023,
  "stockmassCm": 165,
  "datenQuelle": "MANUELL",
  "istAktiv": true,
  "notizenIntern": "string"
}

PUT /api/horses/{id}

Update an existing horse.

Parameters:

• id (path) - UUID of the horse

Request Body: Same as POST

DELETE /api/horses/{id}

Delete a horse.

Parameters:

• id (path) - UUID of the horse

---

Data Models

Person

Represents a person in the system (rider, judge, official, etc.).

Verein (Club)

Represents an equestrian club or association.

Artikel (Article)

Represents items/products that can be sold at events.

Pferd (Horse)

Represents a horse with breeding information and ownership details.

Turnier (Tournament)

Represents an equestrian tournament/competition.

---

Future Enhancements

1. Authentication & Authorization - Implement JWT-based authentication
2. Pagination - Add pagination support for list endpoints
3. Filtering - Add more advanced filtering options
4. Validation - Implement comprehensive input validation
5. Rate Limiting - Add rate limiting for API protection
6. API Versioning - Implement API versioning strategy
7. Documentation - Add OpenAPI/Swagger documentation
8. Caching - Implement caching for frequently accessed data
9. Audit Logging - Add audit trails for data changes
10. Bulk Operations - Support bulk create/update/delete operations

---

Technical Details

• Framework: Ktor (Kotlin)
• Database: PostgreSQL with Exposed ORM
• Serialization: Kotlinx Serialization
• UUID: Multiplatform UUID library
• Date/Time: Kotlinx DateTime

Database Schema

The API is built on top of the following main database tables:

• personen - Person data
• vereine - Club data
• artikel - Article data
• pferde - Horse data
• turniere - Tournament data
• veranstaltungen - Event data
• plaetze - Venue data
• lizenzen - License data

Each table includes standard audit fields (created_at, updated_at) and uses UUIDs as primary keys.