(fix) Statische Startseite im Server-Modul erstellen
This commit is contained in:
@@ -0,0 +1,357 @@
|
||||
# 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:
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
[
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
[
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
[
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user