Reliable API clients

Use the running build's OpenAPI document for request and response schemas. REST, native Redis sessions, generic workflow runs and migration runs have different execution contracts; a successful HTTP submission can precede completion of the requested operation.

Authentication and response parsing

Login with POST /api/v1/auth/login, Basic authentication and X-Org-Id. Refresh Eden-issued tokens with POST /api/v1/auth/refresh and the current bearer. Both return {"token":"..."}. External OIDC token renewal belongs to the issuer. Do not decode a token as a substitute for server authorization.

Parse each operation's response schema and HTTP status. There is no universal status/data success envelope. Typed EdenResponse payloads serialize directly; simple responses can use ok or error. Endpoint data responses also have protocol-specific shapes. Preserve returned operation/run/resource identifiers.

When a protected HA control mutation returns 202, follow its operation_url until its durable result is known. The control operation's accepted/committed state can precede successful local activation. Read the final operation and resource state rather than treating the initial acceptance as completion.

Deadlines, cancellation and retry

Set connect and overall deadlines appropriate to the operation. Use bounded exponential backoff with jitter and a total retry budget for eligible transient failures. Honor Retry-After when supplied; do not assume every limiter emits it. The configured EDEN_RATE_LIMIT is an interval in milliseconds, not an RPS value.

A client timeout, closed socket or cancelled HTTP request is not proof that a backend write was cancelled. Redis INCR, list pops, stream delivery and other effectful commands can execute before a reply is lost. Never retry an uncertain effectful request merely because it used POST or returned no body. Safe retry depends on the operation's actual idempotency and observed delivery evidence.

Long-running work has explicit cancellation APIs. Request cancellation, then observe terminal state and any worker-quiescence evidence before replacement or cleanup. Dropping an SSE connection only stops observation. Redis blocking requests have separate caller/server-wait deadlines and migration restrictions; see Redis command support.

Idempotency is operation-specific

Protected HA control mutations support Idempotency-Key with 1–128 visible ASCII bytes. Persist one key per intended mutation and retain the same actor, organization and request content across retries. Changed intent needs a new key. Reuse can return the original operation or a conflict, depending on the handler's intent checks. Do not assume arbitrary headers deduplicate endpoint writes, migration actions or all REST routes.

Fenced migration recovery uses its own JSON idempotency_key plus expected_operation_id. Other lifecycle actions enforce their own phase, revision and ownership gates. Read the individual schema before retrying.

Pagination and observation

Pagination varies by API. For guided Redis workflow listing, use limit 1–100 and return the opaque next_cursor as cursor on the next request:

curl --fail --silent --show-error --get \
  -H "Authorization: Bearer $EDEN_TOKEN" \
  --data-urlencode 'limit=50' \
  --data-urlencode "cursor=$EDEN_NEXT_CURSOR" \
  "$EDEN_ORIGIN/api/v1/migration-workflows/redis"

Omit cursor for the first page. Stop when next_cursor is absent. Encode query values rather than concatenating cursor bytes into a URL. Concurrent updates can change a traversal; a cursor is not a transactionally frozen export.

Retained telemetry uses limit/offset and bounded time windows instead: default limit 500, maximum 5,000, maximum offset 100,000. Use smaller time windows for larger exports, and retain provider status/completeness information. Never infer an empty dataset from an unavailable provider.

Poll long-running resources with a bounded interval and deadline, or use their documented event stream. After reconnecting an event stream, read durable state again; do not assume every stream supports replay or Last-Event-ID. Record trace IDs when available, without putting credentials or customer values in client logs.