Vai al contenuto

API Reference

OpenAPI / Swagger

L'app espone automaticamente la specifica OpenAPI 3.1 e una UI Swagger:

Risorsa URL (local)
Spec OpenAPI JSON http://localhost:8080/v3/api-docs
Spec OpenAPI YAML http://localhost:8080/v3/api-docs.yaml
Swagger UI http://localhost:8080/swagger-ui.html

Endpoint disponibili

Projects

Metodo Path Body Risposta
POST /api/v1/projects ProjectRequest 201 + Location + ProjectResponse
GET /api/v1/projects?status=&page=&size=&sort= — Page<ProjectResponse>
GET /api/v1/projects/{id} — ProjectResponse
PUT /api/v1/projects/{id} ProjectRequest ProjectResponse
POST /api/v1/projects/{id}/archive — ProjectResponse (idempotente)
POST /api/v1/projects/{id}/reactivate — ProjectResponse
DELETE /api/v1/projects/{id} — 204 No Content

Tasks

Metodo Path Body Risposta
POST /api/v1/projects/{projectId}/tasks TaskRequest 201 + Location + TaskResponse
GET /api/v1/projects/{projectId}/tasks?status=&priority=&page=&size=&sort= — Page<TaskResponse>
GET /api/v1/tasks/{id} — TaskResponse
PUT /api/v1/tasks/{id} TaskRequest TaskResponse
PATCH /api/v1/tasks/{id}/status TaskStatusUpdateRequest TaskResponse
DELETE /api/v1/tasks/{id} — 204 No Content

Modelli

ProjectRequest

{
  "name": "API redesign",            // required, max 120
  "description": "v2 cleanup"         // optional, max 2000
}

ProjectResponse

{
  "id": "9b1f...",
  "name": "API redesign",
  "description": "v2 cleanup",
  "status": "ACTIVE",                 // ACTIVE | ARCHIVED
  "createdAt": "2026-05-20T10:00:00Z",
  "updatedAt": "2026-05-20T10:00:00Z"
}

TaskRequest

{
  "title": "Write docs",              // required, max 200
  "description": "with examples",     // optional, max 2000
  "priority": "HIGH",                 // optional: LOW | MEDIUM | HIGH (default MEDIUM)
  "dueDate": "2026-06-01"             // optional, ISO-8601 date
}

TaskStatusUpdateRequest

{
  "status": "IN_PROGRESS"             // required: TODO | IN_PROGRESS | DONE
}

TaskResponse

{
  "id": "1a2b...",
  "projectId": "9b1f...",
  "title": "Write docs",
  "description": "with examples",
  "status": "TODO",
  "priority": "HIGH",
  "dueDate": "2026-06-01",
  "createdAt": "2026-05-20T10:00:00Z",
  "updatedAt": "2026-05-20T10:00:00Z"
}

Errori — RFC 7807 ProblemDetail

Tutti gli errori seguono lo stesso formato.

400 — Validation

{
  "type": "https://federicocalo.dev/errors/validation",
  "title": "Validation error",
  "status": 400,
  "detail": "Validation failed for one or more fields",
  "errors": [{"field": "name", "message": "must not be blank"}],
  "timestamp": "2026-05-20T18:25:43.511Z"
}

404 — Not Found

{
  "type": "https://federicocalo.dev/errors/not-found",
  "title": "Resource not found",
  "status": 404,
  "detail": "Project with id '9b1f...' not found",
  "resourceType": "Project",
  "identifier": "9b1f...",
  "timestamp": "2026-05-20T18:25:43.511Z"
}

409 — Conflict (state machine / archived project)

{
  "type": "https://federicocalo.dev/errors/conflict",
  "title": "Domain rule violation",
  "status": 409,
  "detail": "Invalid status transition from 'DONE' to 'IN_PROGRESS'",
  "from": "DONE",
  "to": "IN_PROGRESS",
  "timestamp": "2026-05-20T18:25:43.511Z"
}