All jobs

Add Idempotency Keys to a Django REST Framework API

Yes. An agent adds an Idempotency-Key header to your POST APIs, stores each key's response per user, replays it on retry, refuses a changed body, and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads how the APIs are built before it adds a header to them. In a project shaped like HackSoftware/Django-Styleguide-Example, requirements/base.txt pins Django 5.2.7, djangorestframework 3.16.1 and drf-jwt 1.19.2, and requirements/local.txt adds pytest 8.4.2 with pytest-django, mypy 1.18.2 with django-stubs and djangorestframework-stubs, and ruff 0.14.0. Every API is a plain APIView with nested InputSerializer and OutputSerializer classes that call a service: UserCreateApi.post in styleguide_example/users/apis.py validates email and password and calls user_create; FileStandardUploadApi.post in styleguide_example/files/apis.py answers 201 with the new file's id; FileDirectUploadStartApi.post returns presigned upload data. Authentication comes from ApiAuthMixin in styleguide_example/api/mixins.py, which accepts a session cookie, a Session header or a JWT and requires IsAuthenticated.

Two settings matter for how a retry behaves. config/django/base.py sets DATABASES["default"]["ATOMIC_REQUESTS"] = True, so each request is one transaction and a duplicate POST that fails halfway rolls back cleanly. REST_FRAMEWORK["EXCEPTION_HANDLER"] points at drf_default_with_modifications_exception_handler in styleguide_example/api/exception_handlers.py, which wraps every error in {"detail": ...}, so a new refusal has a shape to follow. styleguide_example/common/models.py gives every model created_at and updated_at through BaseModel, and styleguide_example/api is already a Django app with a migrations package, so the new table has a home.

The agent adds an IdempotencyKey model in styleguide_example/api/models.py: key, a foreign key to users.BaseUser, a request_hash of the method, path and body, the stored response_status and response_body as JSON, and a unique constraint on (user, key). An IdempotentPostMixin in styleguide_example/api/mixins.py wraps post: with no Idempotency-Key header the view runs as before; with one, the mixin looks the key up for request.user, replays the stored status and body when the hash matches, answers 422 with {"detail": "Idempotency-Key was used with a different request"} when it does not, and otherwise runs the view and saves the response. A second request that arrives while the first is still inside its transaction hits the unique constraint on insert; the mixin catches that IntegrityError in a savepoint and answers 409 so the caller retries after the first finishes. The mixin goes on UserCreateApi, FileStandardUploadApi and FileDirectUploadStartApi, the three creates that a client is most likely to resend after a timeout.

Tests follow the repository's own style, django.test.TestCase with APIClient and reverse("api:users:create"), in styleguide_example/api/tests/idempotency/: the same key and body twice creates one user and returns the same body and status; the same key with another email is 422; two different users may use the same key; no header keeps the old behaviour. A cleanup_idempotency_keys Celery task in styleguide_example/api/tasks.py deletes rows older than a day, registered through the existing setup_periodic_tasks command under styleguide_example/tasks, since the project already runs django-celery-beat. The agent runs python manage.py makemigrations --check, pytest, ruff check . and mypy --config mypy.ini styleguide_example/, the four commands .github/workflows/django.yml runs, and keeps their output.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add Idempotency-Key support to the POST APIs in this Django REST Framework project and open a pull request. Read requirements/base.txt, requirements/local.txt, config/django/base.py, styleguide_example/api/mixins.py, styleguide_example/api/exception_handlers.py, styleguide_example/users/apis.py, styleguide_example/files/apis.py, styleguide_example/common/models.py and styleguide_example/tasks/management/commands/setup_periodic_tasks.py first. Add an IdempotencyKey model in styleguide_example/api with key, user, request_hash, response_status, response_body and created_at, unique on user and key, with a migration. Add an IdempotentPostMixin beside ApiAuthMixin that replays a stored response when the key and hash match, answers 422 in the project's detail error shape when the body differs, answers 409 when the same key is in flight, and does nothing without the header. Apply it to UserCreateApi, FileStandardUploadApi and FileDirectUploadStartApi. Add a periodic Celery task that deletes keys older than a day. Write tests with APIClient covering replay, changed body, two users sharing a key and no header. Run python manage.py makemigrations --check, pytest, ruff check . and mypy --config mypy.ini styleguide_example/, and paste the output in the pull request.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

What comes back is a pull request with a new model and migration under styleguide_example/api, a mixin added to three API classes, a Celery task and its periodic registration, and a tests package. The description explains the three responses a client can get for a reused key, shows the 422 body in the project's detail shape, and pastes the makemigrations --check, pytest, ruff and mypy output.

The repository's Django application workflow runs the same four commands against a Postgres service on the pull request, so the checks a reviewer sees are the ones already configured, with the new tests included.

A reviewer checks that a request without the header is byte-for-byte unchanged, that stored response bodies never include anything the original response did not, that the hash covers the path so a key cannot replay one API's answer on another, and that the cleanup task's age matches how long their clients retry. They merge when the workflow is green.

Run it on every API that clients retry after a timeout

A team with several Django services sends one POST /o/{org}/sessions per repository, with this prompt and the repository in resources. Each run reads that service's own APIView classes and applies the mixin to its creates, so each pull request names the endpoints it changed rather than a fixed list.

Pass a request_id on each call so a retried start returns the run already in progress, and give the key a webhook_url so run.completed arrives with session_url when the turn ends and your handler posts the pull request link to the channel that reviews backend changes.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

Idempotency is a correctness feature whose bugs only show under concurrency: two requests with the same key at the same moment, a replay across users, a key reused with a different body. In a Rush sandbox the agent runs the test suite against a real Postgres, including the savepoint path that catches the unique constraint, and keeps every command and result in the run's record beside the pull request.

Doing this by hand means touching a model, a migration, a mixin, three views, a Celery task and tests while keeping mypy with django-stubs happy. The agent makes the whole change in one pass with the repository's own checks, and a follow-up such as "also cover the password reset endpoint" wakes the parked sandbox and adds to the same branch.

Frequently asked questions

Why store the response instead of just the key?

Because a client that retries wants the answer it missed, not an error saying the work already happened. Storing response_status and response_body lets the mixin replay the original 201 with the same id, so the client's code path is the same whether or not the first attempt reached it.

Why is the key scoped to the user?

Keys are chosen by clients, and two clients can pick the same UUID. The unique constraint is on (user, key), and the lookup filters by request.user, so one caller can never read another caller's stored response. Views that allow anonymous requests are left out of this change.

What happens if the first request is still running?

The second insert fails on the unique constraint inside a savepoint, so the outer ATOMIC_REQUESTS transaction survives, and the API answers 409 with a detail message asking the client to retry shortly. Once the first request commits, the retry replays its response.

Does this change the endpoints without the header?

No. The mixin returns early when Idempotency-Key is absent, so existing clients see the same status codes and bodies. The tests include a case that sends two identical requests with no header and asserts two users are created, as before.

How long are keys kept?

The pull request sets the cleanup task to delete rows older than a day, which covers the retry windows most HTTP clients use. The age is one constant in styleguide_example/api/tasks.py, and the period is a django-celery-beat schedule the reader can change in the admin.

More Django REST Framework jobs

More jobs like this: Hand off a long task

Keep reading