„Both ways are not user-friendly: the consumer needs to have a reliable mechanism for generating request IDs“
Given that we are talking about payments and those are usually bound to a transaction like an order, there should already be such an identifier, e.g an order ID.
Although your idea looks interesting and nice, this doesn’t seem like the perfect use case for it.
Additionally having some sort of request ID included in the request could make troubleshooting easier if something goes wrong.
About me: software developer who is into JavaScript and NodeJS and constantly working on one or another side project and/or open source. I have a blog at https://alex-rudenko.com
Given that we are talking about payments and those are usually bound to a transaction like an order, there should already be such an identifier, e.g an order ID.
Normally, yes. Even more, if your implementation is thorough enough, you can save all outgoing requests with their request IDs in a database related to the, say, customer record. But is it the best possible way?
Additionally having some sort of request ID included in the request could make troubleshooting easier if something goes wrong.
This is nice in any case. But is there really a need to use the request ID to turn non-idempotent POST requests into idempotent PUT-like requests? I would be really happy if all APIs in the world used at least request IDs to de-duplicate the POST requests. But it's not the best way because those requests IDs in the headers usually are optional and often overlooked. Heck, even PayPal's API doc does not mention it in the section about payment creation. I would prefer APIs to be designed in such way so that it's impossible to double-process things in the first place.
Although your idea looks interesting and nice, this doesn’t seem like the perfect use case for it.
Do you know a better example from your experience to illustrate the problem?
There is no universal answer to that question. Everything has its drawbacks.
But, depending on what you are optimizing for: Yes, it can be the best solution.
In this case there are drawbacks with your solution: it requires a second roundtrip for something that is a single operation, actually.
If you are aiming for a lot of requests this might not be what you want.
Second, one could say that it is not very RESTful, since you are basically introducing state. What if network errors lead to a lot of first requests to happen but not the second one? Then you have records you need to cleanup.
But it's not the best way because those requests IDs in the headers usually are optional and often overlooked.
Now that is a circular argument.
If sending a request ID is required for your use case, then you can use that field and be done with it, isn’t it so?
About me: software developer who is into JavaScript and NodeJS and constantly working on one or another side project and/or open source. I have a blog at https://alex-rudenko.com
for something that is a single operation, actually
I would argue that one can view it as two operations: 1) getting an id for a new resource and 2) creation of the resource using PUT.
it is not very RESTful, since you are basically introducing state
The Request ID also introduces state because the second request with the same ID is rejected. Also, it changes the usual way POST requests work.
Then you have records you need to cleanup.
Indeed, you can clean them up later. It's easier than to cancel a duplicate payment though.
If sending a request ID is required for your use case, then you can use that field and be done with it, isn’t it so?
I would, and I would advocate for providing it, at least. Unfortunately, in practice, it's not always available because it's not a standard way of doing things. I would prefer to have a solution which eliminates duplication by design.
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
„Both ways are not user-friendly: the consumer needs to have a reliable mechanism for generating request IDs“
Given that we are talking about payments and those are usually bound to a transaction like an order, there should already be such an identifier, e.g an order ID.
Although your idea looks interesting and nice, this doesn’t seem like the perfect use case for it.
Additionally having some sort of request ID included in the request could make troubleshooting easier if something goes wrong.
Normally, yes. Even more, if your implementation is thorough enough, you can save all outgoing requests with their request IDs in a database related to the, say, customer record. But is it the best possible way?
This is nice in any case. But is there really a need to use the request ID to turn non-idempotent POST requests into idempotent PUT-like requests? I would be really happy if all APIs in the world used at least request IDs to de-duplicate the POST requests. But it's not the best way because those requests IDs in the headers usually are optional and often overlooked. Heck, even PayPal's API doc does not mention it in the section about payment creation. I would prefer APIs to be designed in such way so that it's impossible to double-process things in the first place.
Do you know a better example from your experience to illustrate the problem?
There is no universal answer to that question. Everything has its drawbacks.
But, depending on what you are optimizing for: Yes, it can be the best solution.
In this case there are drawbacks with your solution: it requires a second roundtrip for something that is a single operation, actually.
If you are aiming for a lot of requests this might not be what you want.
Second, one could say that it is not very RESTful, since you are basically introducing state. What if network errors lead to a lot of first requests to happen but not the second one? Then you have records you need to cleanup.
Now that is a circular argument.
If sending a request ID is required for your use case, then you can use that field and be done with it, isn’t it so?
This is true. I mention this in the post.
I would argue that one can view it as two operations: 1) getting an id for a new resource and 2) creation of the resource using PUT.
The Request ID also introduces state because the second request with the same ID is rejected. Also, it changes the usual way POST requests work.
Indeed, you can clean them up later. It's easier than to cancel a duplicate payment though.
I would, and I would advocate for providing it, at least. Unfortunately, in practice, it's not always available because it's not a standard way of doing things. I would prefer to have a solution which eliminates duplication by design.