mocode-software/meldestelle
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
1bdd5c38aa
meldestelle/docs/api/members-api.md

15 KiB
Raw Blame History

modul status last_reviewed review_cycle summary yt_epic yt_issues tags
members-api active 2025-10-22 180d Dokumentation der Members‑API (Endpunkte, Parameter, Beispiele). MP-1
api
members

Members‑API – Dokumentation

Überblick

Die Members API bietet umfassende Funktionalität zur Verwaltung von Vereinsmitgliedern und deren Mitgliedschaftsdaten. Sie unterstützt vollständige CRUD-Operationen sowie spezialisierte Funktionen für Mitgliedschaftsverwaltung, Validierung und Statistiken.

Basis-Informationen

  • Basis-URL: /api/members
  • Controller: MemberController
  • Authentifizierung: JWT Bearer Token erforderlich
  • Content-Type: application/json
  • Zeichenkodierung: UTF-8

Endpunkte Übersicht

Methode Endpunkt Beschreibung
GET /api/members Alle Mitglieder abrufen
GET /api/members/{id} Mitglied nach ID abrufen
GET /api/members/by-membership-number/{membershipNumber} Mitglied nach Mitgliedsnummer
GET /api/members/by-email/{email} Mitglied nach E-Mail
GET /api/members/stats Mitgliederstatistiken
POST /api/members Neues Mitglied erstellen
PUT /api/members/{id} Mitglied aktualisieren
DELETE /api/members/{id} Mitglied löschen
GET /api/members/expiring-memberships Ablaufende Mitgliedschaften
GET /api/members/by-date-range Mitglieder nach Datumsbereich
GET /api/members/validate/email/{email} E-Mail-Eindeutigkeit prüfen
GET /api/members/validate/membership-number/{membershipNumber} Mitgliedsnummer-Eindeutigkeit prüfen

Detaillierte Endpunkt-Dokumentation

1. Alle Mitglieder abrufen

GET /api/members

Ruft eine Liste aller Mitglieder ab mit optionaler Filterung und Suche.

Query-Parameter

Parameter Typ Standard Beschreibung
activeOnly boolean true Nur aktive Mitglieder anzeigen
limit integer 100 Maximale Anzahl Ergebnisse
offset integer 0 Anzahl zu überspringende Ergebnisse
search string - Suchbegriff für Mitgliedernamen

Beispiel-Anfrage

GET /api/members?activeOnly=true&limit=50&search=Schmidt
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Erfolgreiche Antwort (200 OK)

{
  "data": [
    {
      "memberId": "123e4567-e89b-12d3-a456-426614174000",
      "firstName": "Max",
      "lastName": "Schmidt",
      "email": "max.schmidt@example.com",
      "phone": "+43 1 234 5678",
      "dateOfBirth": "1985-03-15",
      "membershipNumber": "M2024001",
      "membershipStartDate": "2024-01-01",
      "membershipEndDate": "2024-12-31",
      "isActive": true,
      "address": "Musterstraße 123, 1010 Wien",
      "emergencyContact": "Anna Schmidt, +43 1 234 5679",
      "createdAt": "2024-01-01T10:00:00Z",
      "updatedAt": "2024-07-25T12:37:00Z"
    }
  ],
  "success": true,
  "message": null,
  "errors": [],
  "timestamp": "2025-07-25T12:37:00Z"
}

Fehler-Antworten

  • 500 Internal Server Error: Serverfehler beim Abrufen der Mitglieder

2. Mitglied nach ID abrufen

GET /api/members/{id}

Ruft ein spezifisches Mitglied anhand seiner eindeutigen ID ab.

Pfad-Parameter

Parameter Typ Beschreibung
id UUID Eindeutige Mitglieder-ID

Beispiel-Anfrage

GET /api/members/123e4567-e89b-12d3-a456-426614174000
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Erfolgreiche Antwort (200 OK)

{
  "data": {
    "memberId": "123e4567-e89b-12d3-a456-426614174000",
    "firstName": "Max",
    "lastName": "Schmidt",
    "email": "max.schmidt@example.com",
    "phone": "+43 1 234 5678",
    "dateOfBirth": "1985-03-15",
    "membershipNumber": "M2024001",
    "membershipStartDate": "2024-01-01",
    "membershipEndDate": "2024-12-31",
    "isActive": true,
    "address": "Musterstraße 123, 1010 Wien",
    "emergencyContact": "Anna Schmidt, +43 1 234 5679",
    "createdAt": "2024-01-01T10:00:00Z",
    "updatedAt": "2024-07-25T12:37:00Z"
  },
  "success": true,
  "message": null,
  "errors": [],
  "timestamp": "2025-07-25T12:37:00Z"
}

Fehler-Antworten

  • 400 Bad Request: Ungültiges UUID-Format
  • 404 Not Found: Mitglied nicht gefunden
  • 500 Internal Server Error: Serverfehler

3. Mitglied nach Mitgliedsnummer abrufen

GET /api/members/by-membership-number/{membershipNumber}

Pfad-Parameter

Parameter Typ Beschreibung
membershipNumber string Mitgliedsnummer

Beispiel-Anfrage

GET /api/members/by-membership-number/M2024001
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

4. Mitglied nach E-Mail abrufen

GET /api/members/by-email/{email}

Pfad-Parameter

Parameter Typ Beschreibung
email string E-Mail-Adresse

Beispiel-Anfrage

GET /api/members/by-email/max.schmidt@example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

5. Mitgliederstatistiken abrufen

GET /api/members/stats

Ruft Statistiken über die Mitgliederdatenbank ab.

Erfolgreiche Antwort (200 OK)

{
  "data": {
    "totalActive": 1250,
    "totalMembers": 1380
  },
  "success": true,
  "message": null,
  "errors": [],
  "timestamp": "2025-07-25T12:37:00Z"
}

6. Neues Mitglied erstellen

POST /api/members

Erstellt ein neues Mitglied mit den bereitgestellten Daten.

Request Body

{
  "firstName": "Max",
  "lastName": "Mustermann",
  "email": "max.mustermann@example.com",
  "phone": "+43 1 234 5678",
  "dateOfBirth": "1985-03-15",
  "membershipNumber": "M2024002",
  "membershipStartDate": "2024-08-01",
  "membershipEndDate": "2024-12-31",
  "isActive": true,
  "address": "Beispielstraße 456, 1020 Wien",
  "emergencyContact": "Anna Mustermann, +43 1 234 5679"
}

Erfolgreiche Antwort (201 Created)

{
  "data": {
    "memberId": "456e7890-e89b-12d3-a456-426614174001",
    "firstName": "Max",
    "lastName": "Mustermann",
    "email": "max.mustermann@example.com",
    "phone": "+43 1 234 5678",
    "dateOfBirth": "1985-03-15",
    "membershipNumber": "M2024002",
    "membershipStartDate": "2024-08-01",
    "membershipEndDate": "2024-12-31",
    "isActive": true,
    "address": "Beispielstraße 456, 1020 Wien",
    "emergencyContact": "Anna Mustermann, +43 1 234 5679",
    "createdAt": "2025-07-25T12:37:00Z",
    "updatedAt": "2025-07-25T12:37:00Z"
  },
  "success": true,
  "message": null,
  "errors": [],
  "timestamp": "2025-07-25T12:37:00Z"
}

Fehler-Antworten

  • 400 Bad Request: Ungültige Anfragedaten
  • 409 Conflict: E-Mail oder Mitgliedsnummer bereits vorhanden
  • 422 Unprocessable Entity: Validierungsfehler

7. Mitglied aktualisieren

PUT /api/members/{id}

Aktualisiert ein bestehendes Mitglied.

Pfad-Parameter

Parameter Typ Beschreibung
id UUID Eindeutige Mitglieder-ID

Request Body

{
  "firstName": "Max",
  "lastName": "Mustermann",
  "email": "max.mustermann.updated@example.com",
  "phone": "+43 1 234 5678",
  "dateOfBirth": "1985-03-15",
  "membershipNumber": "M2024002",
  "membershipStartDate": "2024-08-01",
  "membershipEndDate": "2025-07-31",
  "isActive": true,
  "address": "Neue Straße 789, 1030 Wien",
  "emergencyContact": "Anna Mustermann, +43 1 234 5679"
}

Erfolgreiche Antwort (200 OK)

Gleiche Struktur wie bei der Erstellung, aber mit aktualisierten Daten und updatedAt Zeitstempel.

Fehler-Antworten

  • 400 Bad Request: Ungültige Anfragedaten oder UUID-Format
  • 404 Not Found: Mitglied nicht gefunden
  • 409 Conflict: E-Mail oder Mitgliedsnummer bereits vorhanden
  • 500 Internal Server Error: Serverfehler

8. Mitglied löschen

DELETE /api/members/{id}

Löscht ein Mitglied aus dem System.

Pfad-Parameter

Parameter Typ Beschreibung
id UUID Eindeutige Mitglieder-ID

Beispiel-Anfrage

DELETE /api/members/123e4567-e89b-12d3-a456-426614174000
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Erfolgreiche Antwort (200 OK)

{
  "data": "Member deleted successfully",
  "success": true,
  "message": null,
  "errors": [],
  "timestamp": "2025-07-25T12:37:00Z"
}

Fehler-Antworten

  • 400 Bad Request: Ungültiges UUID-Format
  • 404 Not Found: Mitglied nicht gefunden
  • 500 Internal Server Error: Serverfehler

9. Ablaufende Mitgliedschaften abrufen

GET /api/members/expiring-memberships

Ruft Mitglieder ab, deren Mitgliedschaft in den nächsten Tagen abläuft.

Query-Parameter

Parameter Typ Standard Beschreibung
daysAhead integer 30 Anzahl Tage im Voraus

Beispiel-Anfrage

GET /api/members/expiring-memberships?daysAhead=14
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Erfolgreiche Antwort (200 OK)

{
  "data": [
    {
      "memberId": "123e4567-e89b-12d3-a456-426614174000",
      "firstName": "Max",
      "lastName": "Schmidt",
      "email": "max.schmidt@example.com",
      "membershipNumber": "M2024001",
      "membershipEndDate": "2025-08-10",
      "daysUntilExpiry": 14
    }
  ],
  "success": true,
  "message": null,
  "errors": [],
  "timestamp": "2025-07-25T12:37:00Z"
}

10. Mitglieder nach Datumsbereich abrufen

GET /api/members/by-date-range

Ruft Mitglieder basierend auf einem Datumsbereich ab.

Query-Parameter

Parameter Typ Erforderlich Beschreibung
startDate string (YYYY-MM-DD) Ja Startdatum
endDate string (YYYY-MM-DD) Ja Enddatum
dateType string Nein MEMBERSHIP_START_DATE oder MEMBERSHIP_END_DATE

Beispiel-Anfrage

GET /api/members/by-date-range?startDate=2024-01-01&endDate=2024-12-31&dateType=MEMBERSHIP_START_DATE
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Fehler-Antworten

  • 400 Bad Request: Ungültiges Datumsformat oder Datumstyp

11. E-Mail-Eindeutigkeit validieren

GET /api/members/validate/email/{email}

Prüft, ob eine E-Mail-Adresse bereits verwendet wird.

Pfad-Parameter

Parameter Typ Beschreibung
email string Zu prüfende E-Mail-Adresse

Query-Parameter

Parameter Typ Beschreibung
excludeMemberId UUID Mitglieder-ID zum Ausschließen (für Updates)

Beispiel-Anfrage

GET /api/members/validate/email/test@example.com?excludeMemberId=123e4567-e89b-12d3-a456-426614174000
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Erfolgreiche Antwort (200 OK)

{
  "data": {
    "isValid": true,
    "isUnique": false,
    "message": "Email address is already in use"
  },
  "success": true,
  "message": null,
  "errors": [],
  "timestamp": "2025-07-25T12:37:00Z"
}

12. Mitgliedsnummer-Eindeutigkeit validieren

GET /api/members/validate/membership-number/{membershipNumber}

Prüft, ob eine Mitgliedsnummer bereits verwendet wird.

Pfad-Parameter

Parameter Typ Beschreibung
membershipNumber string Zu prüfende Mitgliedsnummer

Query-Parameter

Parameter Typ Beschreibung
excludeMemberId UUID Mitglieder-ID zum Ausschließen (für Updates)

Datenmodelle

Member (Mitglied)

{
  "memberId": "UUID",
  "firstName": "string",
  "lastName": "string",
  "email": "string",
  "phone": "string (optional)",
  "dateOfBirth": "string (YYYY-MM-DD, optional)",
  "membershipNumber": "string",
  "membershipStartDate": "string (YYYY-MM-DD)",
  "membershipEndDate": "string (YYYY-MM-DD, optional)",
  "isActive": "boolean",
  "address": "string (optional)",
  "emergencyContact": "string (optional)",
  "createdAt": "string (ISO 8601)",
  "updatedAt": "string (ISO 8601)"
}

CreateMemberRequest

{
  "firstName": "string (required)",
  "lastName": "string (required)",
  "email": "string (required)",
  "phone": "string (optional)",
  "dateOfBirth": "string (YYYY-MM-DD, optional)",
  "membershipNumber": "string (required)",
  "membershipStartDate": "string (YYYY-MM-DD, required)",
  "membershipEndDate": "string (YYYY-MM-DD, optional)",
  "isActive": "boolean (default: true)",
  "address": "string (optional)",
  "emergencyContact": "string (optional)"
}

UpdateMemberRequest

Identisch mit CreateMemberRequest.

MemberStats

{
  "totalActive": "number",
  "totalMembers": "number"
}

Validierungsregeln

Pflichtfelder

  • firstName: Nicht leer
  • lastName: Nicht leer
  • email: Gültige E-Mail-Adresse, eindeutig
  • membershipNumber: Nicht leer, eindeutig
  • membershipStartDate: Gültiges Datum

Geschäftsregeln

  • E-Mail-Adresse muss eindeutig sein
  • Mitgliedsnummer muss eindeutig sein
  • membershipEndDate muss nach membershipStartDate liegen (falls angegeben)
  • Telefonnummer muss gültiges Format haben (falls angegeben)

Fehlerbehandlung

Validierungsfehler (422 Unprocessable Entity)

{
  "data": null,
  "success": false,
  "message": "Validation failed",
  "errors": [
    {
      "field": "email",
      "message": "Email address is invalid",
      "code": "INVALID_EMAIL"
    },
    {
      "field": "membershipNumber",
      "message": "Membership number already exists",
      "code": "DUPLICATE_MEMBERSHIP_NUMBER"
    }
  ],
  "timestamp": "2025-07-25T12:37:00Z"
}

Häufige Fehlercodes

Code Beschreibung
MEMBER_NOT_FOUND Mitglied nicht gefunden
INVALID_EMAIL Ungültige E-Mail-Adresse
DUPLICATE_EMAIL E-Mail bereits vorhanden
DUPLICATE_MEMBERSHIP_NUMBER Mitgliedsnummer bereits vorhanden
INVALID_DATE_FORMAT Ungültiges Datumsformat
INVALID_UUID_FORMAT Ungültiges UUID-Format
MEMBERSHIP_DATE_CONFLICT Enddatum vor Startdatum

Beispiel-Workflows

Neues Mitglied registrieren

  1. E-Mail validieren: GET /api/members/validate/email/{email}
  2. Mitgliedsnummer validieren: GET /api/members/validate/membership-number/{membershipNumber}
  3. Mitglied erstellen: POST /api/members

Mitglied aktualisieren

  1. Aktuelles Mitglied abrufen: GET /api/members/{id}
  2. E-Mail validieren (falls geändert): GET /api/members/validate/email/{email}?excludeMemberId={id}
  3. Mitglied aktualisieren: PUT /api/members/{id}

Ablaufende Mitgliedschaften verwalten

  1. Ablaufende Mitgliedschaften abrufen: GET /api/members/expiring-memberships?daysAhead=30
  2. Für jedes Mitglied: Benachrichtigung senden oder Verlängerung anbieten

Rate Limiting

  • Authentifizierte Anfragen: 1000 Anfragen/Stunde
  • Validierungs-Endpunkte: 100 Anfragen/Minute (zusätzliches Limit)

Caching

  • GET-Anfragen: 5 Minuten Cache (außer Validierungs-Endpunkte)
  • Statistiken: 15 Minuten Cache
  • Cache-Invalidierung: Bei POST/PUT/DELETE-Operationen

Letzte Aktualisierung: 25. Juli 2025 API-Version: v1.0 Controller-Version: MemberController v1.0