With POST you're creating a resource within the resource identified by the Request-URI. The server is responsible for
creating a URI for the new resource you created.
POST /forum/http/
- creates a new post into the HTTP forum
POST /photogalleries/cats/
- uploads a new photo into the cats photo gallery
With PUT the client knows the resource's URI. The client uses it to create or
update the resource. The easiest why to visualize this is to think of a
filesystem
PUT /forum/http/post-vs-put
- upserts a post identified by "post-vs-put" into the HTTP forum
PUT /photogalleries/cats/smelly-cat
- upserts a photo identified by "smelly-cat" into the cat's photo gallery.
To be precise, there's really nothing that you can determine from the resource you're POSTing to. A POST to /forum/http/ could create a new cat picture in /yaykittens/ for all we know.
It's meant to be a catchall method, used for anything the others don't specifically cover.
I've often thought of creating a "Cult of HTTP" that goes door to door and hands out pamphlet versions of Chapter 8 of "RESTful Web Services" to web developers.
Yes, but I have the nagging feeling that it should say "PUT is defined as being idempotent, so it's the responsibility of the programmer to implement it that way." Some frameworks may implement it this way, which is good, but it's something to test for if we want to assume idempotence.
I think either way is okay. It depends on how you want to structure it. Most web APIs aren't entirely RESTful anyway. It is also important to note that a lot of hosting providers don't support other verbs than GET or POST (ie Low-REST) [1].
1. What do you do if you wish to hide a query from the HTTP access log? Normally I would use POST rather than GET, but if I wish to make my API restful I have to ensure that POST is for create, and GET is for read.
2. Does PUT data also not appear in the HTTP access log?
3. What do you gain from doing everything this way? There are a lot of developers that won't have any idea what all of these HTTP request codes and methods actually are.
Figure out how to log only what you want. Don't let your choice of an inflexible logging system affect your external API.
What do you get? Well many things, but specific to your inquiries: using GET tells the client of your API that the request is cache-able (for better performance -- a browser won't cache POSTs), and it tells that client that it's safe to call without unintended consequences. A search engine spider should be safe to just hit every uri via GET that it finds, because those are supposed to be read-only.
1. You don't. Standard practice is to log everything, and more than you think you'll need. If you don't want to see those queries, configure your log viewing process/facility to ignore them.
If you want to put HTTP methods in terms of SQL CRUD then think of it this way.
POST is like a INSERT on a table with a auto incrementing primary key, you insert the data into the table and the SQL server tells you what the data is identified as. When you POST to a web service, the web service tells you what the data is identified as.
For SQL:
INSERT INTO people (first, last) VALUES ("Eric", "Moritz");
SELECT id FROM people WHERE first = "Eric" and last = "Moritz";
For HTTP:
> POST /people/
> Content-Type: application/json
>
> {"first": "Eric", "last": "Moritz"}
< HTTP/1.1 201 Created
< Content-Location: /people/1
<
< {"first": "Eric", "last": "Moritz"}
PUT can function like an UPDATE on a table using it's primary key. For instance:
For SQL:
UPDATE people set first = "Eric" where id = 1;
For HTTP:
> PUT /people/1/first
> Content-Type: text/plain
>
> Eric
< HTTP/1.1 200 OK
< Content-Type: application/json
<
< Eric
A PUT can also be used to create a resource:
For SQL:
INSERT INTO people (id, first, last) VALUES (1, "Eric", "Moritz");
For HTTP:
> PUT /people/1
> Content-Type: application/json
>
> {"first": "Eric", "last": "Moritz"}
< HTTP/1.1 201 Created
<
< {"first": "Eric", "last": "Moritz"}
GET and HEAD are not really "potent" as they don't cause state to change on the server (or at least shouldn't). So I usually prefer saying GET and HEAD are "safe".
The difference between safe and idempotent is:
- using an idempotent verb 0 or 1 times will have a different end state on the server.
- using a safe verb 0 or 1 times will have the same end state on the server.
At the risk of being down-voted by the HN-hive mind (this place is seriously getting as bad as reddit)...
There is a subset of developers in the valley who pride themselves on trying to build the perfect REST API. Arguing over things like PUT v. POST, laughing at people who have to use ?_method= hacks to get around corporate firewalls, and trying to pack as many query parameters into the path as possible. Things like this SO thread really get them excited, so its a magnet for upvotes.
The problem is, while technically correct, this is counter-intuitive to how you should be building an API. Unless you are going to be providing fully functional libraries in all the major languages, your number one goal is making it so damn easy your average contract programmer from Accenture (who often don't even know POST exists) could use it. Unless you have a compelling wealth of data hidden behind your API (Google, eBay, Amazon, etc.), or extreme user demand (Flickr, Facebook, etc.), you have to make the bar to entry as absolutely low as possible or you will never get traction.
The problem with many articles about REST is that they revolve around the question how to make your API more RESTful, and rarely answer why (and if) it actually makes sense to do so.
I think that proper use of HTTP methods is one of the core ideas of REST, but I understand that one might have to take shortcuts like _method to satisfy real-life needs while calling it RESTful to satisfy the buzz-word hungry PHB.
Let's just agree not to do something like GET /foo?_method=DELETE
I agree, this post is a typical reddit post. HN should not allow people under a certain karma to post. This would prevent a lot of sh*t to be post. This would also maybe prevent some startups from launching their product on HN just because they know HN will drive a lot of people on their website.
I agree it's an old question, but the idea is to put up an interesting debate on HN, let people know what is the right way of doing things (in this case REST, which is a misunderstood topic).
We, as developers take some pieces of technology as granted, many of us might not understand the real use cases of usage of PUT vs POST.
I don't think HN is meant purely for "fresh news" but a place for meaningful discussions which matter.
PS: This was not a karma collection ploy by me. If I wanted karma I would go to reddit or stackoverflow. Not HN.
