Add idempotency keys to Flarum API

0.1.0 2021-04-11 17:25 UTC

This package is auto-updated.

Last update: 2024-07-12 00:41:22 UTC


License Latest Stable Version Total Downloads Donate

This extension is meant primarily as a proof of concept, but is fully working. Let me know which use cases you find for it!

It implements optionally idempotent POST requests to Flarum REST API.

It then modifies the Flarum frontend so discussion and post creation uses them.

Idempotency is requested by passing a Idempotency-Key header with a unique value. If another request is made with the same key, it will be ignored and the previous response will be returned again.

Key aspects:

  • Can be used on all POST routes of the REST API, including those registered by extensions.
  • Only works with requests returning an instanceof Laminas' JsonResponse. Attempting to use the idempotency key on a different response type will return in a 400 error, but the request will still be performed!
  • The key has to be unique per actor. Guests cannot use idempotency keys.
  • If the body of the request does not match the original request with the same idempotency key, a 400 error will be thrown.
  • Only successful requests are cached. It's assumed that any thrown exception was before any data was saved.
  • Cache is configured to 24h and is currently not configurable.


  • The extension cannot differentiate between exceptions happening before or after data saving. The choice was made to not cache those requests so they can be attempted again. You should use an async queue to reduce the risk of this happening.
  • The default filesystem cache driver of Flarum will quickly fill with entries and I don't think it auto-cleans expired files. You should probably use a different cache driver on any important forum.
  • Extensions that add headers or modify JSON responses based on some internal state through middlewares might be impacted. It might be necessary to change the boot order of extensions depending on the situation.
  • Race conditions could allow two requests made at the same time to be both executed. Using an async queue driver will help with this issue as the sooner the first request finishes, the sooner a cached response will be available for the second request.


Make sure you understand the description above. Most likely you don't need/want that extension.

composer require clarkwinkelmann/flarum-ext-idempotency


This extension is under minimal maintenance.

It was developed for a client and released as open-source for the benefit of the community. I might publish simple bugfixes or compatibility updates for free.

You can contact me to sponsor additional features or updates.

Support is offered on a "best effort" basis through the Flarum community thread.