API reference
Protocol conventions, common statuses, OpenAPI discovery, and generated endpoint documentation.
SmartGare uses JSON request and response bodies except multipart imports and streaming protocols.
Base URL
Local examples use:
http://localhost:8080Business endpoints are versioned inside their module path, for example
/referential/v1 and /rules/v1.
Authentication
Protected operations accept a bearer JWT:
Authorization: Bearer <your-token>Errors
| Status | Meaning |
|---|---|
400 | Malformed request |
401 | Missing or invalid authentication |
403 | Authenticated but unauthorized |
404 | Aggregate or referenced resource not found |
409 | State, uniqueness, overlap, concurrency, or lifecycle conflict |
422 | Validation or business-input failure |
500 | Unexpected failure without internal disclosure |
The platform uses one typed error shape. Validation and conflict outcomes may carry a field/reason map.
Generated endpoints
Endpoint pages are generated from openapi/smartgare.yaml, exported from the
running Spring application at /v3/api-docs. They include request/response
schemas, parameters, security, and endpoint descriptions.
Regenerate the committed contract after backend route or schema changes:
bun run openapi:generatebun run check rejects an invalid or empty committed specification.
Use the API surface for a capability-oriented map and the generated endpoint tree for operation-level detail.