Skip to main content

Mutation

Gateway prefix: ${API_BASE}/data/mutation...

Backend controller: MutationController (/api/v1/mutation).

Request body fields (MutationRequest)​

Core fields:

  • version: string, required, version (currently "1.0")
  • transaction: boolean, optional, whether to enable transaction (recommended for batch operations)
  • audit: object, optional
    • actor: string, optional
    • reason: string, optional
  • operations: array, required, list of mutation operations (MutationItem)

MutationItem​

  • op: insert | update | upsert | delete, required
  • entity: string, required, entity name
  • values: Array<Record<string, any>>, optional (commonly used for insert/upsert)
  • match_on: string[], optional (commonly used for upsert, specify match fields)
  • set: Record<string, any>, optional (for update)
  • where: Predicate, optional (for update/delete)
  • optimistic_lock: object, optional
    • field: string, required
    • expected: any, optional
  • returning: string[], optional (fields to return)
  • cascade: boolean, optional
  • validate: array, optional (server-side expression validations)
    • expr: string, required
    • message: string, optional

Predicate uses the same structure as in Query (comparison/logical/not).

Execute mutation (recommended entry)​

  • POST /mutation/execute
  • Permissions: isAuthenticated()

Headers:

  • Authorization: Bearer <token>
  • X-Tenant-Id: <tenantId>
  • Content-Type: application/json

Example: insert​

curl -X POST \
  "${API_BASE}/data/mutation/execute" \
  -H "Authorization: Bearer <token>" \
  -H "X-Tenant-Id: tenant-abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1.0",
    "transaction": true,
    "operations": [
      {
        "op": "insert",
        "entity": "customers",
        "values": [
          { "name": "Alice", "email": "alice@example.com", "age": 18 }
        ],
        "returning": ["id"]
      }
    ]
  }'

Example: update (where + set)​

curl -X POST \
  "${API_BASE}/data/mutation/execute" \
  -H "Authorization: Bearer <token>" \
  -H "X-Tenant-Id: tenant-abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1.0",
    "transaction": true,
    "operations": [
      {
        "op": "update",
        "entity": "orders",
        "where": { "type": "comparison", "field": "id", "op": "eq", "value": 10001 },
        "set": { "status": "PAID" }
      }
    ]
  }'

Example: upsert (match_on)​

curl -X POST \
  "${API_BASE}/data/mutation/execute" \
  -H "Authorization: Bearer <token>" \
  -H "X-Tenant-Id: tenant-abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1.0",
    "transaction": true,
    "operations": [
      {
        "op": "upsert",
        "entity": "customers",
        "match_on": ["email"],
        "values": [
          { "name": "Alice", "email": "alice@example.com" }
        ]
      }
    ]
  }'

Example: delete​

curl -X POST \
  "${API_BASE}/data/mutation/execute" \
  -H "Authorization: Bearer <token>" \
  -H "X-Tenant-Id: tenant-abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1.0",
    "transaction": true,
    "operations": [
      {
        "op": "delete",
        "entity": "orders",
        "where": { "type": "comparison", "field": "id", "op": "eq", "value": 10001 }
      }
    ]
  }'

Batch execute mutations​

  • POST /mutation/batch
  • Permissions: isAuthenticated()
  • Request body: MutationRequest[]

Validate mutation DSL​

  • POST /mutation/validate
  • Permissions: permitAll
  • Request body: MutationRequest

Convenience endpoints (equivalent to execute)​

  • POST /mutation/insert
  • PUT /mutation/update
  • DELETE /mutation/delete