90 lines
2.6 KiB
Markdown
90 lines
2.6 KiB
Markdown
# 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
|