57 lines
7.4 KiB
JSON
57 lines
7.4 KiB
JSON
{
|
|
"openapi": "3.1.0",
|
|
"info": {"title": "InvestMoz Simulation Execution API", "version": "1.0.0", "description": "Indicative arithmetic scenarios. Rates and reductions are user supplied, not legal rates or eligibility decisions."},
|
|
"servers": [{"url": "/api/v1"}],
|
|
"paths": {
|
|
"/simulation-drafts": {
|
|
"post": {"summary": "Create an encrypted, versioned simulator form draft", "parameters": [{"$ref": "#/components/parameters/IdempotencyKey"}, {"$ref": "#/components/parameters/SimulationToken"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SimulationFormDraft"}}}}, "responses": {"201": {"description": "Created with ETag"}, "200": {"description": "Idempotent replay"}, "409": {"description": "Draft exists or key reused with a different payload"}, "422": {"description": "Invalid draft field"}}}
|
|
},
|
|
"/simulation-drafts/current": {
|
|
"get": {"summary": "Read the current user's or anonymous token's draft", "parameters": [{"$ref": "#/components/parameters/SimulationToken"}], "responses": {"200": {"description": "Draft snapshot and ETag; personal fields are decrypted only for its owner"}}}
|
|
},
|
|
"/simulation-drafts/{id}": {
|
|
"get": {"summary": "Read an owned draft", "parameters": [{"$ref": "#/components/parameters/Id"}, {"$ref": "#/components/parameters/SimulationToken"}], "responses": {"200": {"description": "Draft snapshot and ETag"}, "404": {"description": "Draft inaccessible"}}},
|
|
"put": {"summary": "Autosave an owned draft with optimistic locking", "parameters": [{"$ref": "#/components/parameters/Id"}, {"$ref": "#/components/parameters/IfMatch"}, {"$ref": "#/components/parameters/SimulationToken"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SimulationFormDraft"}}}}, "responses": {"200": {"description": "Saved with new ETag and snapshot hash"}, "412": {"description": "Stale draft version"}, "422": {"description": "Invalid draft field"}}},
|
|
"delete": {"summary": "Soft-delete an owned draft", "parameters": [{"$ref": "#/components/parameters/Id"}, {"$ref": "#/components/parameters/IfMatch"}, {"$ref": "#/components/parameters/SimulationToken"}], "responses": {"204": {"description": "Deleted"}, "412": {"description": "Stale draft version"}}}
|
|
},
|
|
"/questionnaires/{code}": {"get": {"summary": "Read the published Portuguese questionnaire version", "parameters": [{"name": "code", "in": "path", "required": true, "schema": {"type": "string"}}], "responses": {"200": {"description": "Published questionnaire and stable version", "headers": {"ETag": {"schema": {"type": "string"}}}}, "404": {"description": "No published current version"}}}},
|
|
"/simulations": {
|
|
"post": {
|
|
"summary": "Create a traceable simulation",
|
|
"parameters": [{"$ref": "#/components/parameters/IdempotencyKey"}, {"$ref": "#/components/parameters/SimulationToken"}],
|
|
"requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SimulationInput"}}}},
|
|
"responses": {"202": {"description": "Execution queued", "headers": {"ETag": {"schema": {"type": "string"}}, "Location": {"schema": {"type": "string"}}}}, "200": {"description": "Idempotent replay"}, "409": {"description": "Key reused with a different payload"}, "422": {"description": "Invalid input or missing anonymous token"}, "428": {"description": "Idempotency-Key required"}}
|
|
}
|
|
},
|
|
"/simulations/{id}": {
|
|
"get": {"summary": "Read a simulation and its snapshots", "parameters": [{"$ref": "#/components/parameters/Id"}, {"$ref": "#/components/parameters/SimulationToken"}], "responses": {"200": {"description": "Simulation", "headers": {"ETag": {"schema": {"type": "string"}}}}, "404": {"description": "Missing or outside authorized scope"}}}
|
|
},
|
|
"/simulations/{id}/scenarios/{scenarioId}": {
|
|
"patch": {
|
|
"summary": "Update a scenario with optimistic concurrency",
|
|
"parameters": [{"$ref": "#/components/parameters/Id"}, {"$ref": "#/components/parameters/ScenarioId"}, {"$ref": "#/components/parameters/IfMatch"}, {"$ref": "#/components/parameters/SimulationToken"}],
|
|
"requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/UpdateScenarioInput"}}}},
|
|
"responses": {"202": {"description": "Updated; re-execution queued"}, "403": {"description": "Edit not authorized"}, "404": {"description": "Simulation inaccessible"}, "412": {"description": "Stale ETag"}, "428": {"description": "If-Match required"}, "422": {"description": "Invalid input"}}
|
|
}
|
|
},
|
|
"/simulations/{id}/reports/{reportId}": {
|
|
"get": {"summary": "Read an immutable report snapshot", "parameters": [{"$ref": "#/components/parameters/Id"}, {"$ref": "#/components/parameters/ReportId"}, {"$ref": "#/components/parameters/SimulationToken"}], "responses": {"200": {"description": "Report snapshot and hash"}, "404": {"description": "Report inaccessible"}}}
|
|
}
|
|
},
|
|
"components": {
|
|
"parameters": {
|
|
"Id": {"name": "id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}},
|
|
"ScenarioId": {"name": "scenarioId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}},
|
|
"ReportId": {"name": "reportId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}},
|
|
"IdempotencyKey": {"name": "Idempotency-Key", "in": "header", "required": true, "schema": {"type": "string", "minLength": 16, "maxLength": 128}},
|
|
"SimulationToken": {"name": "X-Simulation-Token", "in": "header", "required": false, "description": "Required for anonymous access. Client generated; only an HMAC hash is stored.", "schema": {"type": "string", "minLength": 32, "maxLength": 256}},
|
|
"IfMatch": {"name": "If-Match", "in": "header", "required": true, "description": "Strong ETag; absent returns 428, stale returns 412.", "schema": {"type": "string"}}
|
|
},
|
|
"schemas": {
|
|
"SimulationInput": {"type": "object", "additionalProperties": false, "required": ["base", "rate", "reduction"], "properties": {"base": {"type": "number", "minimum": 0, "description": "User input; no currency is inferred."}, "rate": {"type": "number", "minimum": 0, "maximum": 100, "description": "User scenario rate; not an official rate."}, "reduction": {"type": "number", "minimum": 0, "maximum": 100, "description": "User supplied scenario reduction; no default is applied."}, "organization_id": {"type": "string", "format": "uuid", "description": "Optional; requires admin, manager or officer membership."}}},
|
|
"SimulationFormDraft": {"type": "object", "additionalProperties": false, "required": ["personal_snapshot", "economic_snapshot"], "properties": {"personal_snapshot": {"type": "object", "description": "Allowlisted personal fields, encrypted at rest; only owner/token can read."}, "economic_snapshot": {"type": "object", "required": ["purpose"], "description": "Allowlisted economic/form fields, encrypted at rest; rates remain user-supplied."}}},
|
|
"UpdateScenarioInput": {"type": "object", "additionalProperties": false, "required": ["label", "base", "rate", "reduction"], "properties": {"label": {"type": "string", "minLength": 1, "maxLength": 100}, "base": {"type": "number", "minimum": 0}, "rate": {"type": "number", "minimum": 0, "maximum": 100}, "reduction": {"type": "number", "minimum": 0, "maximum": 100, "description": "User supplied scenario reduction; no default is applied."}}}
|
|
}
|
|
}
|
|
}
|