API Design

API-First Principle

The Membership platform follows an API-first development approach: every feature is designed as an API endpoint before any frontend screen is built. The API is the product -- the Flutter apps, admin web interface, third-party integrations, and future AI agents all consume the same API.

Phase 1 (v1.0): REST API with JSON payloads. This is the only API style implemented at launch. Phase 2: GraphQL endpoint for flexible querying (admin dashboards, reporting). Runs alongside REST, not as a replacement. Phase 3: MCP (Model Context Protocol) interface for AI agent integration. Webhook system for event-driven third-party integration.

All API styles share the same authentication, authorization, and business logic layer. Only the transport/serialization layer differs.

Current Consumer API (V1)

The existing mb-api module provides 25 endpoints across 9 controllers under the /mobile/v1/ prefix. These serve the consumer-facing mobile app.

Authentication Endpoints

Consumer Profile Endpoints

Contract and Membership Endpoints

Financial Endpoints

Entity and Organization Endpoints

Device and Access Control Endpoints

Missing Endpoints (Identified in Review)

The following endpoints are required by the mobile app specification but do not exist in the current codebase.

Authentication Gaps

POST /mobile/v1/account/resend-verification

Resend the email verification link. Required when the original email is lost or expired.

Request:  (empty body, uses JWT to identify user)
Response: { "status": "OK", "message": "Verification email resent" }
Rate limit: 1 request per 60 seconds per user

POST /mobile/v1/account/refresh-token

Exchange a valid refresh token for a new access token + refresh token pair. Enables silent re-authentication without storing credentials on device.

Request:  { "refreshToken": "eyJ..." }
Response: { "accessToken": "eyJ...", "refreshToken": "eyJ...", "expiresIn": 3600 }
Note: Refresh token rotation -- old refresh token is invalidated on use

POST /mobile/v1/account/logout

Invalidate the current session. Revokes the refresh token server-side and clears any server-side session state.

Request:  (empty body, uses JWT to identify session)
Response: 204 No Content

Consumer Profile Gaps

GET /mobile/v1/account/export-data

GDPR data export. Returns all personal data associated with the account in a machine-readable format (JSON). Required by EU GDPR Article 20 (right to data portability).

Request:  (empty body, uses JWT)
Response: {
  "account": { "email": "...", "createdAt": "...", "verifiedAt": "..." },
  "profile": { "firstName": "...", "lastName": "...", ... },
  "contracts": [ ... ],
  "transactions": [ ... ],
  "bankAccounts": [ ... ],
  "accessLogs": [ ... ]
}
Note: May be asynchronous for large accounts (returns job ID, notifies via email when ready)

Bank Account Gaps

PUT /mobile/v1/bank-account/{id}

Update an existing bank account (e.g., correct IBAN, change account holder name).

Request:  { "iban": "DE89...", "accountHolder": "Max Mustermann", "bic": "COBADEFFXXX" }
Response: { "id": 42, "iban": "DE89...", "accountHolder": "...", "statusCd": "ACTIVE" }
Constraint: Cannot update a bank account that has pending SEPA transactions

DELETE /mobile/v1/bank-account/{id}

Delete (archive) a bank account. Soft delete -- the account is marked as archived but retained for historical transaction reference.

Request:  (empty)
Response: 204 No Content
Constraint: Cannot delete the last active bank account if active contracts require SEPA payment

New API Areas

Beyond the consumer-facing mobile API, the Membership platform requires four additional API domains for the admin interface, resource management, events, and reporting.

Admin API (/api/v1/admin/)

The admin API provides full CRUD operations for all domain entities, accessible only to users with Club Admin role or higher. All admin endpoints enforce multi-tenant isolation via the authenticated user's entity context.

Resource Management API (/api/v1/resources/)

Designed as a standalone-capable API (see Chapter 06). All endpoints work both within the Membership platform and as an independent resource management service.

Events and Courses API (/api/v1/events/)

Communication API (/api/v1/communication/)

CRM and Sales API (/api/v1/crm/)

Support and Ticketing API (/api/v1/support/)

Accounting API (/api/v1/accounting/)

Vendor API (/api/v1/vendor/)

Platform-level API for Membership One (vendor) operations. Requires Vendor Admin or Vendor Support role. All endpoints operate cross-tenant.

Access Control API (/api/v1/access/)

API Versioning

URL-Based Versioning

All endpoints include the version in the URL path:

/mobile/v1/account/login       (consumer mobile API, version 1)
/api/v1/admin/members          (admin API, version 1)
/api/v2/admin/members          (admin API, version 2, when needed)

Version Lifecycle

Migration Rules

• Breaking changes (field removal, type change, behavior change) require a new version.
• Additive changes (new optional fields, new endpoints) do not require a new version.
• The consumer mobile API (/mobile/v1/) and admin API (/api/v1/) are versioned independently.

Authentication

JWT Token Structure

Authentication uses JWT tokens issued by the Membership backend (not an external IdP in v1). The token is included in the Authorization header as a Bearer token.

Access Token Claims:

{
  "sub": "user@example.com",
  "iss": "membership-api",
  "iat": 1740000000,
  "exp": 1740003600,
  "userId": 12345,
  "entityId": 67,
  "roles": ["CLUB_ADMIN"],
  "type": "access"
}

Token Lifecycle:

Refresh Token Rotation: When the access token expires, the client sends the refresh token to /mobile/v1/account/refresh-token. The server returns a new access token AND a new refresh token. The old refresh token is immediately invalidated. This limits the damage window if a refresh token is compromised.

Token Revocation: On logout or password change, all refresh tokens for the user are revoked server-side. Active access tokens continue to work until expiration (max 1 hour). For immediate revocation (e.g., account compromise), the server maintains a short-lived blacklist in Redis.

Pagination Standard

All list endpoints support cursor-based or offset-based pagination. The default is offset-based (consistent with Spring Data's Pageable).

Request Parameters

Response Envelope

{
  "content": [ ... ],
  "page": {
    "number": 0,
    "size": 20,
    "totalElements": 150,
    "totalPages": 8
  },
  "sort": {
    "field": "createdAt",
    "direction": "DESC"
  }
}

For endpoints where offset pagination is inefficient (large datasets, real-time feeds), cursor-based pagination is used:

{
  "content": [ ... ],
  "cursor": {
    "next": "eyJpZCI6MTIzNH0=",
    "hasMore": true
  }
}

Rate Limiting

Rate limits protect the API from abuse and ensure fair usage across tenants.

Rate limit headers (included in every response):

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1740003660

When exceeded:

HTTP 429 Too Many Requests
Retry-After: 30

Rate limits are enforced using Redis sliding window counters, which survive server restarts and work correctly across multiple API server instances.

Error Response Format

All errors follow a standardized format, regardless of the endpoint or error type.

Standard Error Object

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request contains invalid data.",
    "details": [
      {
        "field": "email",
        "message": "Email address is already registered.",
        "code": "DUPLICATE_EMAIL"
      },
      {
        "field": "iban",
        "message": "Invalid IBAN checksum.",
        "code": "INVALID_IBAN"
      }
    ],
    "timestamp": "2026-02-22T14:30:00Z",
    "traceId": "abc-123-def-456"
  }
}

Error Codes

Error Design Principles

• Error messages are user-friendly in the message field (suitable for display in the UI).
• Technical details (stack traces, SQL errors) are never included in the response. They are logged server-side with the traceId for debugging.
• Validation errors include per-field detail so the frontend can highlight specific form fields.
• The traceId enables correlation between the client error report and server logs.

Cash360 Payment API Integration

The Membership platform delegates all payment processing to Cash360 via its REST API. This is a server-to-server integration -- the Membership backend calls Cash360; the Membership frontend never talks to Cash360 directly.

Integration Architecture

Integration Points

Authentication Between Services

Service-to-service authentication uses a dedicated API key (not user JWT). The API key is stored in environment variables and included in the X-API-Key header. Each Membership tenant has a separate API key that maps to a Cash360 entity (idMcEntity), ensuring multi-tenant isolation at the payment layer.

X-API-Key: mb-tenant-67-a1b2c3d4e5f6...

OpenAPI / Swagger Documentation

Documentation Strategy

Every endpoint is documented using SpringDoc OpenAPI annotations directly in the controller code. This ensures that the documentation stays synchronized with the implementation.

Annotations used: - @Operation(summary, description) on each endpoint method - @Parameter(description, required, example) on path/query parameters - @Schema(description, example) on DTO fields - @ApiResponse(responseCode, description) for each possible response status

Access

Generated Artifacts

The build pipeline extracts the OpenAPI spec as: - openapi.json -- Machine-readable spec, used by code generators (Flutter client, Postman collection) - openapi.yaml -- Human-readable spec, committed to version control for change tracking - Swagger UI -- Interactive documentation for developers

Client Code Generation

The Flutter API client is generated from the OpenAPI spec using openapi-generator-cli with the Dart/Dio template. This eliminates manual DTO maintenance in the frontend and guarantees type-safe API calls that match the current backend contract.

openapi-generator-cli generate \
  -i openapi.json \
  -g dart-dio \
  -o frontend/lib/core/api/generated/

The generated client is checked into version control and regenerated whenever the API spec changes.