DEV Community

Discussion on: Making Better HTTP APIs

Collapse
orkon profile image
Alex Rudenko Author

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?

Collapse
aptituz profile image
Patrick Schönfeld

But is it the best possible way?

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?

Thread Thread
orkon profile image
Alex Rudenko Author

it requires a second roundtrip

This is true. I mention this in the post.

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.