ADD support for idempotent subscription creation

[tzzed]

Is your feature request related to a problem / use case? Please describe.
When deploying subscriptions automatically (e.g. via CI/CD or infrastructure as code), it is easy to create duplicates of the same subscription unintentionally. Currently, Orion allows the creation of multiple subscriptions with the same parameters (e.g. same description, subject, notification). This results in multiple redundant notifications being sent, which can be problematic in production environment

Describe the solution you'd like
I would like a mechanism to prevent the creation of duplicate subscriptions. This could take several forms:

Return an HTTP 409 Conflict if an identical subscription already exists (based on a defined uniqueness criteria).

Support a rejectIfExists flag in the POST /v2/subscriptions request body.

Support a user-defined idempotencyKey or allow description to be a unique key.

Example request:

POST /v2/subscriptions
Content-Type: application/json

{
  "description": "Notify when temperature > 30",
  "subject": { ... },
  "notification": { ... },
  "rejectIfExists": true
}

If a subscription with the same description, subject, and notification already exists, the creation should fail gracefully.

Describe alternatives you've considered

• Listing all subscriptions (GET /v2/subscriptions) and manually comparing them before creating a new one — but this introduces complexity and race conditions.

• Deleting all subscriptions before recreating them — but this breaks idempotency and causes temporary unsubscription.

Describe why you need this feature

• To improve and simplify infrastructure automation and avoid race conditions.
• To ensure subscriptions are unique and avoid redundant notifications.
• To help maintain clarity and reduce load on both Orion and subscribers.

Additional information
Add any other information, diagrams or screenshots about the feature request here.
This behavior is common in modern APIs that support idempotent creation. It would also be useful in orchestrated systems like Kubernetes or Terraform.
Do you have the intention to implement the solution

• Yes, I have the knowledge to implement this new feature.
• Yes, but I will need help.
• No, I do not have the skills.

[fgalan]

@tzzed thanks for your feedback!

One comment: instead of using "rejectIfExists": true in the payload, it's better to use a query param, like:

POST /v2/subscriptions?options=rejectIfExists
...

Given that this "flavour" is a kind of indication on how to create the subscription but not part of the subscription itself.

Btw, this old issue seems to be related: #1117. I'd suggest you to have a look to it (although it is pretty old). Probably both can be solved at the same time.

[fgalan]

If a subscription with the same description, subject, and notification already exists, the creation should fail gracefully.

Note that subject and notification are JSON objects

https://github.com/telefonicaid/fiware-orion/blob/master/doc/manuals/orion-api.md#subscriptionsubject
https://github.com/telefonicaid/fiware-orion/blob/master/doc/manuals/orion-api.md#subscriptionnotification

Not sure if we have currently functionality to do deep-compare of JSON objects in the Orion code (in that case, it should be reused).

[tzzed]

Hi @fgalan

You're right, using ?options=rejectIfExists makes much more sense than adding a field to the payload.

That said, comparing full subscription JSON objects to detect duplicates can be expensive and error-prone (e.g., due to field ordering or irrelevant differences). To optimize this, maybe we could allow a more explicit comparison strategy, like:

POST /v2/subscriptions?options=checkIfExist&entities=Room&url=http://notify

This would let the broker check for existing subscriptions based on a minimal, well-defined set of fields (like target entities and notification URL), instead of comparing the entire subscription body. Just an idea to consider for better performance and control.

[fgalan]

That would be more flexible, but would make user experience more complex, as the user has to provide a set of additional fields (entities=, url=).

I think is preferable to keep it simple for the user (i.e. only the options=checkIfExist) although it involves doing JSON deep-compare in Orion code (especially if the functionality is already in the code and it is a matter of reusing it).

Just a though :)