feat: add idempotency guidance (#456) #479
Conversation
|
👍 for the actual rule changes, I didn't review the formatting stuff in detail. |
|
@duergner @maxim-tschumak @ePaul Thanks for reviewing so far. Has one had the time to although have a look at spelling mistakes and grammar so far? |
|
👍 Nice work, thx. |
| |==================================================== | ||
|
|
||
| [#229] | ||
| == {SHOULD} Consider To Design `POST` and `PATCH` Idempotent |
There was a problem hiding this comment.
Should it be MAY instead? According to RFC-2119 for SHOULD
mean that there
may exist valid reasons in particular circumstances to ignore a
particular item, but the full implications must be understood and
carefully weighed before choosing a different course.
As far as I understand this in context of API guideline it means that I should provide a valid reason NOT to not implement POST and PATCH idempotent. In other words if POST implemented, then it should be idempotent, otherwise provide a valid reason not doing this. I think it is too "strong".
There was a problem hiding this comment.
Thanks, nice discussion start.
I personally would like it to be understood this way. There are to many drawbacks when having non-idempotent behavior, e.g. for create zombie or duplicate resources, for update incorrect values, etc.
I would vote clearly for SHOULD.
|
@vadeg @maxim-tschumak @tfrauenstein @duergner @whiskeysierra @ePaul @zeitlinger @gewald Thanks for all the great feedback and discussions. I have tried to incorporate all of them. Lets go into the last round for approvals, prove reading, and or voting for #479 (comment). I would really like to merge this work today 😸! |
|
👍 |
|
👍 |
|
👍 |
chapters/http-requests.adoc
Outdated
| request body. The _secondary key_ is stored permanently in the resource. It | ||
| allows to ensure <<idempotent>> behavior by looking up the resource in case | ||
| of multiple independent resource creations from different clients (see | ||
| <<231>>). |
There was a problem hiding this comment.
Can you explain this a bit better, what is a a "resource specific secondary key" ?
Is it a property that has a uniqueness constraint enforced server-side?
There was a problem hiding this comment.
Exactly. Do you think I should add "(property with uniqueness constraint)" here? Or would it be enough to add this to rule 231, that is linked here?
There was a problem hiding this comment.
@cjbooms tried to be clearer about uniqueness requirements. Please have a look.
There was a problem hiding this comment.
I think a property with uniqueness constraint enforced server-side is a more concise definition. It covers the wide variety of ways this could be achieved, and is not at all ambiguous.
There was a problem hiding this comment.
@cjbooms I have reworded this: please read https://github.com/zalando/restful-api-guidelines/pull/479/files#diff-c98f51639d3d10ea65dae4c0de86666fR266 ff and https://github.com/zalando/restful-api-guidelines/pull/479/files#diff-c98f51639d3d10ea65dae4c0de86666fR310 ff to look whether it is sufficient.
|
👍 |
1 similar comment
|
👍 |
Fixes #456.