One of the characteristics of a good REST API is that it uses the standard HTTP methods in a way they are supposed to be used. We hear this all the...
For further actions, you may consider blocking this person and/or reporting abuse
I usually think of PUT as a replace.
A practical example is saving a new file B to the location of an existing file A.
Likewise, I think of PATCH as a merge.
A practical example is writing a new field value B to a SQL record A. The resulting SQL record C contains fields from both A and B.
Completely agree with you. That perfectly describes what
PUTandPATCHshould do.I avoided using that terminology as I have seen that developers new REST style find it difficult to understand that. And then there is this.
Maybe, this is a topic for its own blog?
I think idempotence is more important than the verbs.
Using only
POSThas benefits too.GETan URLYes, idempotence is important but it goes hand in hand with verbs. Browsers and API clients work on the assumption that a POST verb is never idempotent and will behave accordingly so it is important to keep that relationship intact.
I agree with the points you make about advantages of using a POST verb to hide sensitive data.
Browsers and API clients work on the assumption that a POST verb is never idempotent and will behave accordingly
Does this mean, they assume other verbs to be always idempotent and also behave accordingly?
I used POST as an example in my statement. What I wanted to say that they will assume what the standard says and behave accordingly.
What about checking for authorization before returning such GET requests? Wouldn't it be another way of protecting sensitive data.
I may be misunderstanding your point but it goes without saying that you always properly protect your API, no matter HTTP method is being used.
Nice article, I didn't focus on PATCH and idempotency so far.
Reading through the article a question arose: say we have an entity with an 'updated_at' attribute where we store the timestamp of the last update.
Since the 'updated_at' is changed every time we save the entity, saving through a PUT method would break the idempotency, is it correct?
In this case, should we consider to use a PATCH to update that kind of entities?
Thank you!
It really depends on how your resources are represented.
One way to keep PUT still idempotent in that case would be to treat
updated_atas a server generated value which the client has no control over, which is actually true in most cases. The from a client's perspective, the resource representation they send to the server is same every time and server can respond in an idempotent manner.Ok, that means that a GET shouldn't return the 'updated_at' attribute?
Sorry if I bother :)
Why should it not?
Resource for
PUTandGETcan look different.Just asking :)
Thank you for your clarification, it was very useful
Great article, it is good to know about the specs of the HTTP methods, however you can't rely on every client respecting the specification!
Take a look at OkHttp, a Java HTTP client, very popular with android. OkHttp will potentially repeat your requests on a slow/unreliable connection “aggressively” until it succeeds.. It doesn't matter if it is a request with an idempotent method or not, even POST request are retried until the client gets a valid response. OkHttp mantainers argued that everything should be idempotent by default, and unless the client retries the request agressively under the hood on flaky connections, the only way to know whether the request succeeded or not is to make another request at the application layer, which is not pretty. Initially mantainers suggested users to fix their API backends but later they included a flag to disable this. It's been like that for years now.
I have very briefly used OkHttp so thanks for bringing this up.
Without getting into why OkHttp decided to aggressively retry even the POST requests, I find the reasoning presented in the medium article half-baked (for the lack of a right word). When you are in the control of the backend API then you can make decisions that go against the standards like HTTP e.g. making POST requests idempotent. However, a good software developer should consider the following two situations
It is a good news that OkHttp now allows disabling this feature. There are better ways to deal with slow internet connections.
Is this article about REST or "REST" (HTTP API)?
I started with REST but ended up writing about REST (HTTP API) ;-)
Can I ask the difference, for my own understanding? Is there something about this that isn't RESTful?
Can I ask the difference? Is there something about this explanation that isn't RESTful, or is it just that REST covers a broader scope than this article?
REST definitely covers a broader scope than this article - the most important being Hypermedia. This article touches upon a tiny subset of REST.
@ben there's a couple of encoding errors at the top of this article
I have fixed the encoding error now. Thanks for pointing out.
Thanks! I really love this article <3