# API - AI Context

## Overview

OpenAPI 3.0.3 specification serves as the **single source of truth** for all API contracts. Both frontend and backend clients are auto-generated from this spec.

---

## API Endpoints

```
# Forms
GET/POST   /application-forms
GET/PUT/DELETE /application-forms/{id}
POST       /application-forms/{id}/submit

# Templates
GET/POST   /application-form-templates
GET/PUT/DELETE /application-form-templates/{id}

# Versions
GET        /application-forms/{id}/versions
GET        /application-forms/{id}/versions/{n}
POST       /application-forms/{id}/versions/{n}/restore
GET        /application-forms/{id}/versions/{n}/pdf

# Comments
GET        /application-forms/{id}/comments
POST       /application-forms/{id}/form-elements/{elementId}/comments
PUT/DELETE /comments/{id}

# Notifications
GET        /notifications?organizationId=
GET        /notifications/unread/count?userId=&organizationId=  (public)
PUT        /notifications/{id}/mark-read
PUT        /notifications/mark-all-read
DELETE     /notifications/clear-all
```

---

## Key Files

| File | Purpose |
|------|---------|
| `legalconsenthub.yml` | OpenAPI 3.0.3 specification (source of truth) |

---

## API-First Workflow

1. **Modify OpenAPI spec** (`api/legalconsenthub.yml`)
   - Add/update endpoints, request/response schemas
   - Follow OpenAPI 3.0.3 standards
   - Document all parameters and responses

2. **Generate clients**
   ```bash
   # Frontend TypeScript client
   cd legalconsenthub && pnpm run api:generate

   # Backend Kotlin server stubs
   cd legalconsenthub-backend && ./gradlew generate_legalconsenthub_server
   ```

3. **Implement backend logic**
   - Server stubs are generated, implement the actual business logic
   - Use mapper classes for DTO ↔ Entity conversions

4. **Use frontend client**
   - Auto-generated TypeScript client available in frontend
   - Type-safe API calls with full IDE support

---

## Rules for AI

1. **Never skip OpenAPI spec** - All API changes must start here
2. **Validate spec** - Ensure OpenAPI 3.0.3 compliance before generating clients
3. **Document everything** - All endpoints, parameters, responses, and schemas must be documented
4. **Breaking changes** - Consider versioning strategy for breaking API changes
5. **Regenerate clients** - Always regenerate both frontend and backend clients after spec changes

### Schema Design Guidelines
- Use `$ref` for reusable components
- Define clear request/response schemas
- Include validation constraints (min/max, pattern, required)
- Use enums for fixed value sets
- Document all fields with descriptions