DEV Community: Borino88

Designing an Idempotent Transaction API: Preventing Duplicate Financial Operations

Borino88 — Sun, 26 Jul 2026 10:54:56 +0000

In financial backend systems, network retries represent a classic race-condition vector. If a client attempts to post a transaction, suffers a TCP timeout, and blindly retries, the backend risks posting the transaction twice.

To prevent duplicate financial operations, we must design an Idempotent API using Idempotency Keys.

The Architecture of Idempotency

sequenceDiagram
    participant Client
    participant API Gateway
    participant Redis Cache
    participant PostgreSQL

    Client->>API Gateway: POST /journal (Idempotency-Key: X)
    API Gateway->>Redis Cache: SetNX(Key: X, Status: IN_PROGRESS)
    alt Key exists
        Redis Cache-->>Client: 409 Conflict (Request In Progress) or Cached Response
    else Key is new
        API Gateway->>PostgreSQL: Execute Double-Entry Transaction
        PostgreSQL-->>API Gateway: Transaction Committed successfully
        API Gateway->>Redis Cache: Set(Key: X, Status: DONE, Response: Y)
        API Gateway-->>Client: 201 Created (Transaction Details)
    end

Core Database Schema & Unique Constraints

We enforce idempotency at the database level by binding the idempotency key directly to our journal entries table:

CREATE TABLE journal_entries (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    idempotency_key VARCHAR(255) UNIQUE NOT NULL,
    amount DECIMAL(18, 4) NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

Python Implementation (FastAPI & Redis)

Here is a tested pattern for validating and caching requests in Redis:

from fastapi import FastAPI, Header, HTTPException, status
import redis

app = FastAPI()
r = redis.Redis(host='localhost', port=6379, decode_responses=True)

@app.post("/api/v1/journal", status_code=201)
def post_transaction(payload: dict, idempotency_key: str = Header(...)):
    # 1. Atomic Check-and-Set in Redis
    lock_acquired = r.set(f"idemp:{idempotency_key}", "IN_PROGRESS", nx=True, ex=3600)

    if not lock_acquired:
        status_val = r.get(f"idemp:{idempotency_key}")
        if status_val == "IN_PROGRESS":
            raise HTTPException(
                status_code=status.HTTP_409_CONFLICT,
                detail="Transaction in progress. Please wait."
            )
        # Return cached response if done
        return {"status": "success", "cached": True, "data": status_val}

    try:
        # 2. Process transaction inside a database transaction block
        # (DB commit logic goes here)
        result_data = {"transaction_id": "tx_abc123", "processed": True}

        # 3. Update status to completed and store response
        r.set(f"idemp:{idempotency_key}", str(result_data), ex=86400)
        return {"status": "success", "cached": False, "data": result_data}
    except Exception as e:
        r.delete(f"idemp:{idempotency_key}")
        raise HTTPException(
            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
            detail="Transaction failed."
        )

Testing for Concurrency

To ensure that concurrent requests with the exact same idempotency key are rejected, we can run multithreaded HTTP request tests using pytest and httpx.

You can view the full repository and test suites at secure-fintech-ledger.

Disclosure: This article was prepared with AI-assisted editing and research support. I reviewed the technical content, tested the code and take responsibility for the final article. #ABotWroteThis

A Practical Multi-Stage Docker Build for Python APIs

Borino88 — Sun, 26 Jul 2026 10:54:51 +0000

When containerizing Python web applications for production, developers often produce heavy, insecure images containing compilers, headers, and root execution privileges.

This post demonstrates how to build a hardened, multi-stage Docker container utilizing a non-root runtime environment, health check verification, and OCI image metadata.

The Production Dockerfile

This multi-stage Dockerfile uses python:3.11-slim-bookworm to separate building dependencies from runtime execution:

# ==============================================================================
# Stage 1: Build & Dependency Packaging
# ==============================================================================
FROM python:3.11-slim-bookworm AS builder

WORKDIR /build

RUN apt-get update && apt-get install -y --no-install-recommends \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

COPY requirements.txt .
RUN pip install --no-cache-dir --prefix=/install -r requirements.txt

# ==============================================================================
# Stage 2: Production Runtime
# ==============================================================================
FROM python:3.11-slim-bookworm AS runtime

# OCI Standard Metadata Labels
LABEL org.opencontainers.image.title="Secure API Platform"
LABEL org.opencontainers.image.source="https://github.com/Borino88/secure-api-platform"
LABEL org.opencontainers.image.version="1.0.0"
LABEL org.opencontainers.image.licenses="MIT"
LABEL org.opencontainers.image.authors="Mahdi Fattahi <a.borino88@gmail.com>"

ENV PYTHONUNBUFFERED=1 \
    PYTHONDONTWRITEBYTECODE=1 \
    PATH="/usr/local/lib/python3.11/site-packages:/app:$PATH" \
    PYTHONPATH="/app"

RUN groupadd -g 1000 appgroup && \
    useradd -u 1000 -g appgroup -s /bin/bash -m appuser

WORKDIR /app

COPY --from=builder /install /usr/local
COPY requirements.txt ./
COPY src/ ./src/

RUN chown -R appuser:appgroup /app

USER appuser

HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
  CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health').getcode() == 200" || exit 1

EXPOSE 8000

CMD ["uvicorn", "src.api.main:app", "--host", "0.0.0.0", "--port", "8000"]

Security Best Practices Highlighted

Multi-Stage Separation: All compiler tools and cached wheels remain in Stage 1, leaving Stage 2 clean.
Non-Root Execution: We define appuser and appgroup to prevent root execution attacks.
Health Checks: A native, dependency-free Python health check endpoint verification command is integrated directly.
Vulnerability Mitigation: Hardened bases limit base image CVE counts, validated using Trivy scans.

The configuration templates are available in the public secure-api-platform repository.

Disclosure: This article was prepared with AI-assisted editing and research support. I reviewed the technical content, tested the code and take responsibility for the final article. #ABotWroteThis

Hello DEV — I’m Mahdi, a Full-Stack Engineer Building Reliable Systems and Open Tools

Borino88 — Sun, 26 Jul 2026 10:54:17 +0000

Hello DEV Community! I'm Mahdi, a senior full-stack engineer and international STEM educator. Over the past eight years, I've designed and shipped software systems spanning financial ledgers, microservice messaging hubs, real-time telemetry dashboards, and geospatial environmental pipelines.

I joined DEV to share hard-earned architectural patterns, dockerized deployment templates, and tested source code that solves real software engineering problems.

What I’m Building

Currently, I'm focusing on two major tracks:

System Reliability & Security: Developing API platforms with integrated rate-limiting, double-entry financial ledgers, and secure integration webhooks.
Open Educational Simulators: Packaging complex math, physics, biology, and computer science concepts into reproducible, interactive open-source laboratories.

What You Can Expect From My Posts

I believe technical articles are only as good as the code that backs them. Therefore, every tutorial or architecture breakdown I write will:

Include fully tested, runnable code.
Address trade-offs, performance limitations, and security considerations.
Link back to public, containerized GitHub repositories so you can spin up the stack instantly.

I look forward to engaging with the community, learning from your experiences, and building in public.

You can view my source code on GitHub.
Check out my interactive portfolio at fattahi.xyz.

Disclosure: This article was prepared with AI-assisted editing and research support. I reviewed the technical content, tested the code and take responsibility for the final article. #ABotWroteThis