I've learned that idempotent requests must return the same response given that the same request sent. But not really sure how to implement this in Nestjs Architecture ? If resource has been already created and duplicate request was recognized, then this resource should be returned. I doubt the logic must be in the service level...
I've tried to use interceptors, but as far as I know they cannot but handle request. I mean, I cannot do something like "Hey, I know this request, so return this stored data and do not handle it twice".
But ok, there're middlewares for that. I can send response before main handling request. But it this case, I cannot cache/store the response of the request... Just because with middlewares I cannot have access to response object.
Any ideas?
by definition idempotent HTTP method (as a result from a request is
An HTTP method is idempotent if an identical request can be made once or several times in a row with the same effect while leaving the server in the same state.
so caching is not exactly what makes the method handler idempotent but rather the actions made by it.
if you want to cache the results of a request you can use nestjs built-it CacheInterceptor. use it either globally, per controller or even per method handler (same as every interceptor).
first import the caching module to your needed module (or root module and make it global) CacheModule.register({ isGlobal: true, }) and then decorate your controller/method handler with it #UseInterceptor(CacheInterceptor).
using the interceptor globally can be done in several ways but the mot straight forward is the simple app.useGlobalInterceptors(new CacheInterceptor())
Note: it only caches GET requests out-of-the-box so if you need other you can extend it to add your logic
Related
A microservice I develop exposes a single endpoint, PUT /deployments/{uuid} . The endpoint is used to initiate a potentially expensive deployment operation, so we only ever want it to happen once, which is why we chose PUT + UUID over POST (for uniqueness). The deployment is immutable, so it can never be updated, so we currently raise an exception if the PUT is called more than once with the same uuid.
As a person who loves bikeshedding and therefore cares deeply about restfulness, this grinds my gears. PUT is supposed to be idempotent, so raising an exception after making the same request multiple times is an antipattern. However, we have a requirement to not allow sequential identical requests to generate new deployments, so the usual POST is out.
While the best solution is one that works, I'd like ours to be a little more elegant, if possible. I've posited a POST with the UUID in the payload, but my team seems to think that's worse than the current solution. I'm considering just returning a 200 OK from a PUT to the same UUID rather than a 201 CREATED, but I'm not sure if that has the same problem as non-idempotent-put in not semantically conveying the information I want.
Is there a "best solution" here? Or am I doomed to be "that guy" on my team if I pursue this further (joke's on you i'm already that guy).
tl;dr What is the correct RESTful API signature for a /deployments endpoint that is immutable, and required to not allow the same request to be processed twice?
Idempotent does not mean "2 identical requests should yield the same response". It means: "The server state after 2 identical requests should be the same as when only 1 is made".
A similar example, if you call DELETE on a resource and get a 204 No Content back, and call DELETE again and get a 404, this doesn't violate the idempotency requirement. After the second delete the resource is still removed, just like it was after the first.
So multiple identical idempotent requests are allowed to give different responses.
That said though, I think it might be nicer to the second identical request to also get a 2xx status back. It doesn't have to be the same as the first.
The use-case is if a client sent a HTTP request but got disconnected before it got a response. The client should retry and if the server detects the request is the same as the first, the server can just give the client a success response (but don't do anything).
This is generally a good idea, because if the client got an error back for the second request, it might be harder to know if the request failed because it succeeded earlier, or for other reasons.
That all being said though, there is also a way here to have your cake and eat it too.
A client could send the following header along with the PUT request:
If-None-Match: *
If the client omits the header, you can always return 424 Precondition Required.
If the resource does not yet exist, it's a success response. If the resource was created earlier, you can return 412 Precondition Failed.
Using this mechanism a client has a standard way to figure out that the request failed because a successful one was made earlier.
Based on the docs here, PUT is the best method to use. The response should be 201 when it triggers the deployment, and either 200 or 204 when nothing is changed. It shouldn't be POST because calling a POST endpoint twice should trigger the effect both times.
Say I have an endpoint for creating an object that takes time to complete which has the following URL structure: /api/v1/objects.
Business rules dictate that API consumers can either call this endpoint synchronously or asynchronously in the server. The result of this call in the end is the creation of the same object, but response upon submission of the endpoint is different between the two depending on whether it is called synchronously or asynchronously (i.e. if the call is made asynchronously, a consumer may get an identifier with no guarantee if the object will be created or not, while calling the endpoint synchronously will always create the object and return it in the response.)
Right now I have this structure for distinguishing between the synchronous and asynchronous API calls:
POST /api/v1/objects - for creating the object synchronously.
POST /api/v1/objects?async=true - for creating the object
asynchronously.
Is this approach correct and conforms to RESTFul principles?
If you look at the RFC for HTTP (see https://www.rfc-editor.org/rfc/rfc7231#section-5.1.1 ) you can see the Expect header, which basically defines what behaviour the client is expecting from the server.
Considering you can have different 20* responses (200, 201, 202, 204), you can use this to determine whether it should be async or not.
A quick Google search comes up with this example (which I copy and paste here for future reference):
A client may request the server to modify its asynchronous behavior
with the following “Expect” headers:
“Expect: 200-ok/201-created/204-no-content” disables all asynchronous
functionality. The server may return a “417 Expectation Failed” if it
is not willing to wait for an operation to complete.
“Expect: 202-accepted” explicitly request an asynchronous response. The server
may return a “417 Expectation Failed” if it is not willing to perform
the request asynchronously. If no expectation is provided, client must
be prepared to accept a 202 Accepted status for any request other than
GET.
I have an application that needs to send multiple (change) requests to the server at a time. These requests are being sent in a batch, represented by a JSON object. The requests can be of any (change) type (e.g. creations, updates, deletions).
the JSON looks something like this:
[
{ "delete": { "id": "to delete" } },
{ "update": { "id": "to update", "data": {} } },
{ "create": { "data": {} } },
...
]
My question is simple:
If I was sending these over to the server one at a time, I'd use DELETE, PUT or POST depending on the nature of the operation, but since I'm sending over a batch potentially containing all three types of requests, I'm not sure which method is most appropriate (aside from DELETE).
Which is the correct HTTP Method to use in this instance?
Thanks.
The correct method to use is a POST method since you are creating a batch-process resource. In addition, you should respond with a 202 Accepted status code which indicates "The request has been accepted for processing, but the processing has not been completed." (RFC 2616)
I hope this helps!
UPDATE:
This should definitely be a POST method because this request IS NOT idempotent. Before you continue, please see What is idempotency in HTTP methods? and Is REST DELETE really idempotent?.
If this request is made multiple times, it may have n number of side-effects (because it creates resources)!
I retracted my PUT recommendation comment because I misspoke—PUT should be idempotent.
Well, AFAIK, there is no such method to do so. You can use just the json as in your post with a new POST request.
This new request will parse the data sent and call delete method on delete related data, put on put related data, and so on.
If I was sending these over to the server one at a time, I'd use DELETE, PUT or POST depending on the nature of the operation, but since I'm sending over a batch potentially containing all three types of requests, I'm not sure which method is most appropriate (aside from DELETE).
Which is the correct HTTP Method to use in this instance?
"It depends".
The key point is this: http semantics apply to resources, which live in the integration domain. The fact that these representations you are sending impact the domain model in interesting ways isn't relevant.
The method you choose should have unsafe semantics, since you are encouraging the origin server to change. You also need a method where the message body is meaningful. Of the methods defined within the HTTP spec, you have PUT and POST -- either of these is fine. PATCH may also be suitable, depending on whether or not you can make this collection of changes atomically.
Example: suppose what we are really doing is taking the body of the message, and sticking it into a queue to be handled "later". The REST part is taking that implementation, and dressing it up with an HTTP disguise.
Either PUT or POST is perfectly fine for that. Using POST to add something to a queue should not be a big surprise. PUT is analogous to inserting the message into a key value store.
HTTP is an application protocol whose application domain is "the transfer of documents over a network." -- Jim Webber
What you have at your client is a document, which happens to describe changes that you want to make in your domain model. You are using HTTP to transmit a copy of that document to the server. Does POST work for that? Yes. Does PUT work for that? also yes.
Consider this resource, which means exactly what it says on the tin
/newest-message-in-queue
Can you update that resource by sending a new representation via POST? Sure. Can you update that resource by sending a PUT? Of course. Will the side effects on the domain objects work either way? Yes.
Can the client tell the difference between this, and changing a value in a key value store? No <-- and that's the point; we're disguising our implementation behind a generic document store semantics, so that we can take advantage of off-the-shelf-ware.
As it was mentioned here https://restfulapi.net/http-methods/ (and in other places as well):
GET APIs should be idempotent, which means that making multiple
identical requests must produce same result everytime until another
API (POST or PUT) has changed the state of resource on server.
How to make this true in an API that return time for example? or that return data that is affected by time.
In other words, each time I use GET http://ip:port/get-time-now/, it is going to return a different response. However, I did not send any POST or PUT between two sequenced GET's
Does this make the previous statement wrong? Did I misunderstand something?
Idempotency is a promise to clients/intermediaries that the request can be reissued in case of network failures or the like without any further considerations and not so much that the data will never change.
If you take a POST request for example, in case of a network failure you do not know if the previous request reached the server but the response got lost midway or if the initial request didn't even reach the server at all. If you re-issue the request you might create a further resource actually, hence POST is not idempotent. PUT on the other side has the contract that it replaces the current representation with the one contained in the request. If you send the same request twice the content of the resource should be the same after any of the two PUT requests was processed. Note that the actual result can still differ as the service is free to modify the received entity to a corresponding representation. Also, between sending the data via PUT and retrieving it via GET a further client could have updated the state in between, so there is no guarantee that you will actually receive the exact representation you've sent to the service.
Safetiness is an other promise that only GET, HEAD and OPTIONS supports. It promises the invoker that it wont modify any state at all hence clients/intermediaries are safe on issuing such request without having to fear that it will modify any state. In practice this is an important promise to crawlers which blindly invoke any URLs in order to learn their content. In case of violating such promises, i.e. by deleting data while processing a GET request the only one to blame is the service implementor but not the invoker. If a crawler invokes such URLs and hence removes some data it is not the crawlers fault actually but only the service implementor.
As you have a dynamic value in your response, you might want to prevent caching of responses though as otherwise intermediaries might return an old state for your resource
The main basic concept of idempotent and safe methods of HTTP:-
Idempotent Method:- The method can called multiple times with same input and it produce same result.
Safe Method:- The method can called multiple times with same input and it doesn't modify the resource onto the server side.
Http methods are categorized into following 3 groups-
GET,HEAD,OPTIONS are safe and idempotent
PUT,DELETE are not safe but idempotent
POST,PATCH are neither safe & nor idempotent
We have a REST API which, for certain operations, we provide the option of asynchronous requests. For async requests, the service will return immediately with a token which can be used to query for completion, while for synchronous requests, the response will not be returned until the operation completes.
The current design for this looks something like this:
URL: PUT /api/orders/1234?async=true
Request Body: customerName=My Company&city=Dallas
Intuitively, it seems wrong to mix query and form params like this, however the query param (async) is providing options to the service call and not an attribute of the resource. That was the primary reason we did not include it in the request body.
Does this approach seem like a good design, or is there a better more "REST-y" way to accomplish the same?
The Prefer header is designed to do exactly what you are trying to do. See the spec.
An URL like this
POST /api/orders/1234?async=true
is not RESTful. Why POST? This looks like RPC over HTTP.
What are your resources? If there is some computation involved, model the computation as resources. POST to a collection of compuations to create a new one. Receive a Location header for the result of the computation.
POST /api/orders
custoerName=My Company
city=Dallas
This could return a response like:
201 Created
Location: /api/orders/1234
Then the client could GET the result:
GET /api/orders/1234
And the server would respond:
200 OK
Some result body.
How to make this asynchronouse?
You write:
however the query param (async) is providing options to the service call and not an attribute of the resource
This is plain wrong. Everything that is in the URI is used to identify the resource. REST is not about calling methods with parameters.
I recommend to always use the two-step-approach described above when modeling compuations/transactions/shopping carts as resources. Create it, retrieve it.