358 lines
7.2 KiB
Markdown
358 lines
7.2 KiB
Markdown
# 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.
|