Repository navigation
OpenAPI: declare the optional isolationLevel request body on POST /api/v1/begin/{database} #10295
Description
POST /api/v1/begin/{database} accepts an optional JSON body carrying isolationLevel, but the OpenAPI spec doesn't declare it. createBeginPath() in CoreApiSpec sets no requestBody, so clients generated from the spec have no way to open a transaction at a chosen isolation level.
What the server does today
PostBeginHandler reads it:
final String isolationLevel = payload != null ? payload.getString("isolationLevel", null) : null;
if (isolationLevel != null)
database.begin(Database.TRANSACTION_ISOLATION_LEVEL.valueOf(isolationLevel));
else
database.begin();So the accepted values are exactly the engine enum, READ_COMMITTED and REPEATABLE_READ. Anything else fails valueOf.
Requested
Declare an optional application/json request body on beginTransaction:
isolationLevel: string,enum: [READ_COMMITTED, REPEATABLE_READ], optional. Absent means the database's default isolation.- Document the response to an unknown value (it should be a 400 from the
IllegalArgumentExceptionarm, not a 500).
A related inconsistency in gRPC (for awareness)
The gRPC TransactionIsolation enum offers four values, and ArcadeDbGrpcService.mapIsolationLevel silently maps READ_UNCOMMITTED to READ_COMMITTED and SERIALIZABLE to REPEATABLE_READ. A gRPC caller who asks for SERIALIZABLE gets a weaker level with no signal. HTTP, by contrast, rejects anything outside the engine enum. It would help to document the downgrade on the proto enum, or refuse levels the engine doesn't provide.
Context
This came up downstream in ArcadeData/arcadedb-drivers#152. The drivers generate their typed surface from the published contract, so they can't expose HTTP isolation until the spec declares it.
Activity
feat(#10295): declare the optional isolationLevel body of POST /api/v…
robfrank commentedon Oct 18, 2026
Fixed in #10318. The OpenAPI spec now declares the optional request body of
POST /api/v1/begin/{database}, withisolationLevelas an enum generated from the server's own list, so the spec and the server stay in sync. An unknown or non-string value now returns a 400 that names the parameter and lists the allowed values, and no session is created. Before, a one-element array was silently accepted and other bad values produced a rawNo enum constanterror. For gRPC, the docs now say thatSERIALIZABLEruns asREPEATABLE_READandREAD_UNCOMMITTEDasREAD_COMMITTED.Still open:
SERIALIZABLEwithout any runtime signal. The behavior is documented but unchanged.read_committedis refused), same as before.❤️ Thanks for helping make ArcadeDB better! ArcadeDB is free and open source, sustained by its community. If it's useful to you or your company, please consider becoming a sponsor to keep development going.
feat(#10295): declare the optional isolationLevel body of POST /api/v…