API conventions

Every StackRivet endpoint — including the ones the code generator emits — follows the same conventions, under the base path /api/v1. The exhaustive endpoint catalog is the live OpenAPI 3.1 document; this page is the contract those endpoints share.

# the full, always-current catalog:
open http://127.0.0.1:8080/swagger-ui.html      # interactive
curl http://127.0.0.1:8080/v3/api-docs           # raw OpenAPI JSON

Response envelope

Every response is wrapped, with a traceId you can correlate to server logs:

{ "code": "0", "message": "OK", "data": {}, "traceId": "01J..." }

code: "0" means success. The HTTP status is also meaningful (StackRivet does not collapse everything to 200) — code is the stable, machine-branchable contract; HTTP status is the transport-level signal.

A paginated data:

{ "items": [], "page": 1, "pageSize": 20, "total": 0 }

HTTP status

Status	When
200 / 201 / 202	success / created / async task accepted
400	bad parameters
401 / 403	unauthenticated / unauthorized
404	not found
409	state / unique-key / version conflict
413 / 415	upload too large / unsupported type
429	rate limited
500	server error

Error codes

The error code is a stable, never-localized contract — clients branch on it. The wire format is {PREFIX}_{REASON}_{HTTP}:

{ "code": "SYSTEM_USER_DUPLICATED_409", "message": "...", "details": [], "traceId": "01J..." }

Prefixes include AUTH, PERM, VALIDATION, SYSTEM, ASSET, SIGNED_URL, GENERATOR, TASK. All codes come from the ErrorCode registry in stackrivet-common; the message is localized by Accept-Language (falling back to English), but the code is not. A build-time gate keeps every code’s English and Chinese message in sync.

Pagination & sorting

Param	Default	Details
page	1	1-based
pageSize	20	max 200
sort	—	e.g. createdAt,desc; whitelisted fields only

sort accepts only whitelisted fields — arbitrary SQL columns are never passed through.

Types

• Timestamps are ISO 8601 strings.
• Precision-sensitive values (money, ratios) are strings or integer minor units — never a float.
• Enums are lowercase strings; booleans are JSON booleans; IDs are strings.

Headers

Authorization: Bearer <access_token>
X-Request-Id: optional-client-request-id
Idempotency-Key: optional — for endpoints that explicitly document idempotency support

• Tokens are short-lived and revocable; a forced logout invalidates the old token. Tokens never appear in logs.
• Send an Idempotency-Key only where the endpoint explicitly documents support for it. StackRivet uses it for async task submission so retries do not duplicate heavy jobs.
• Heavy operations (import, export, large generator writes) return 202 with a task ID rather than holding the request thread — track them via tasks.

API groups

OpenAPI tags map to path prefixes: Auth (/auth), Me (/me), Users, Departments, Posts, Roles, Menus, Dictionaries, Params, Audit, Assets, Generator, Tasks, System — all under /api/v1.