Idempotency keys

[AndrewIngram]

I'm trying to figure out the best way to handle idempotency keys, much like Stripe's API and the draft spec (https://tools.ietf.org/id/draft-idempotency-header-01.html).

I can add the requirement for an idempotency header to any endpoint, doing something like this:

def my_endpoint(
    request, 
    input: InputSchema,
    idempotency_key: str = Header(..., alias="Idempotency-Key")
):
    ...

The problem is that the logic needs to be managed outside the endpoint handler, because it needs to work for all status codes, including validation failures.

The approximate algorithm should be something like this:

1. Request starts
2. Run auth to get the appropriate API user
3. Check if endpoint requires an idempotency check, ideally it's declared via some kind of decorator (e.g. @api.idempotent)
4. If it does:
   1. Key is missing: Bad request. End
   2. Key not yet used: write a pending record to the database with the key, API user, and request signature (essentially a hash of the relevant inputs)
   3. Key used but pending: return 409 Conflict response. End
   4. Key used and committed: return saved response. End
5. Handle request
6. Regardless of status code (200, 201, 400, 500 etc), write the response data to the pending record, and mark it as committed
7. Return response.

I'm struggling find the best way to inject this behaviour with Django Ninja. My best course of action so far seems to be to override the urls property of the NinjaAPI class and wrap any qualifying views, but I'm wondering if there's a better way.

[vitalik]

@AndrewIngram

Just trying to imagine some simple case - let's say there is a form where user clicks a button and a comment created

user can click 2-3 times (because of faulty mouse) - but we want to to create only one record in database

if that case is just for few methods/endpoints - I would use decorator (in decorator you have access to request and header and can store for key processing status)

if you want some global handling (like for all POST/PUT/PATCH methods) I would do this with django middlewares layer (the only issue is patching generated openapi schema to document required headers)

[AndrewIngram]

For the decorator approach, I can't see how it would work by itself.

Let's say we have:

@api.post(
    "/my-endpoint",
    response=Output
)
def my_endpoint(request, input: Input):
    ...

A decorator would presumably have to go between the function definition and api.post, so that the function can be wrapped to add the header to the signature. But the function would still only ever be called if the input validation passes, which means the wrapper would never see requests that fail validation.

Essentially, I can't see anything to wrap that'd give me access to the full request/response lifecycle for a given endpoint.

[vitalik]

I think if you getting validation error - 2nd request with same data will give the same error - so it's kinda idempotent (unless there is a current time related validation)

but yeah - if you want to add some functionality BEFORE validations - the only way is to use middlewares

[AndrewIngram]

Hm yeah, we have an age-based constraint, so it'd technically be possible (though very unlikely) to violate idempotency that way.

[AndrewIngram]

I'm currently trying to implement this using the decorator approach, I think it should mostly be possible to match Stripe's semantics this way. Will share the pattern if it works out.

[AndrewIngram]

Managed to get it working. There were a few gnarly bits related to exception handling, but using the magic _ninja_contribute_args and _ninja_contribute_to_operation properties was very useful for augmenting the original operation.

This is a very hastily (i.e. don't expect it to work just by copy/pasting) extracted version of the solution: https://gist.github.com/AndrewIngram/9d3dd742d1801e898add1e2aa5130639

That said, in my mind the eventual solution highlighted the value of a possible middleware/extension system as being able to hook into different parts of the schema definition and request/response lifecycle would be very useful for this kind of problem. I'll give it some thought and might start another discussion for that.

[vitalik]

some plugin acutally exist already - https://pypi.org/project/django-idempotency-key/

[AndrewIngram]

Answer extracted from a comment:

Managed to get it working. There were a few gnarly bits related to exception handling, but using the magic _ninja_contribute_args and _ninja_contribute_to_operation properties was very useful for augmenting the original operation.

This is a very hastily (i.e. don't expect it to work just by copy/pasting) extracted version of the solution: https://gist.github.com/AndrewIngram/9d3dd742d1801e898add1e2aa5130639