Should API calls be GET or POST?

Question

I noticed that some APIs like the Twitter API use get methods for everything, so the parameters are passed in the URL like this:

http://api.twitter.com/1/statuses/user_timeline.json?screen_name=screenname 

I have some questions and would appreciate comments or corrections:

1. I always thought that using GET is not a good idea, and that it's better to use POST.

2. The API I'm coding requires a key, and I don't think it's a good idea to send it in the URL. So, is it possible to mix both POST parameters and URL parameters?

3. Another problem is that I hear URLs have a max length, so I guess that would make GET out of the way, or is there a workaround?

4. The only problem I'm seeing with POST (and which I'm guessing is why a site like twitter went with GET) is that the request can't be made directly from the browser. Correct me if I'm wrong on this.

---

Updates: Thanks to everyone who's helping me brainstorm this. I have some updates to clarify some of the comments.

1. When I was talking about not wanting to send the key in the URL, what I meant is that I don't want the key bookmarked if a user were to bookmark a call, not that I don't want the key exposed at all. So I guess from the answers that I could send it in the header field? Any other options?

2. I want to clarify that when I said POST requests can't be made from the browser, I should have said, POST requests can't be made from the URL as in http://example.com/api/op.json?param=value. Sorry, I misspoke, should have been clearer.

3. Re whether it's RESTful or not: I've done RESTful before with an MVC framework that took care of detecting the verbs and the URLs ended up looking like example.com/entry/1, or example.com/entry/ and the HTTP verbs are what controlled the operation being performed (create, update, delete, list). I thought, in a practical sense, that RESTful was most useful for crud-like data (create entry, get entry, update entry, delete entry, show all entries). So if I don't need crud, do I need REST? My question: if a call simply gives input and returns output, does this API need to be RESTful? The URL doesn't look RESTful, so is there something else in the implementation that could make it RESTful?

4. As to the URL size, you commented but if you're seriously concerned about it you probably should rethink your API. GET requests shouldn't be sending that much data to the server. So I have this example: user wants to send a large file. On the server, I won't enter the file into the database or save it (so according to standards I'm not "posting" data), but maybe I'm (these are quickly thought examples, so please take them loosely):

• (a) reading the metadata of the file and returning it (should that be GET or POST), or
• (b) I'm reading the metadata and modifying the metada on the file and returning the modified file (should that be GET or POST).
• So this is an example of why I might need to send large data. The question is are (a) and (b) considered GET or POST operations? and this is why I was asking about the URL max length

Answer 1

1. I always thought that using GET is not a good idea and that it's better to use POST.

Use GET for reading information, POST for writing information. GET requests shouldn't modify server-side state, while POST requests can safely do so. In general use GET for reads and POST for writes. Your API should probably use a mixture of both, depending on which each specific API call does.

2. The API I'm coding requires a key, and I don't think it's a good idea to send it in the URL. So is it possible to mix both POST parameters and URL parameters?

Sending data via POST doesn't add any level of security at all. GET requests are no less insecure than POST requests; they are identical. For transferring private data, use SSL.

You should ideally use an HTTP header like Authorization to transmit the key, as this is less likely to be logged by intermediaries, or to be emitted to 3rd party services like bug-trackers.

3. Another problem is that I hear URLs have a max length, so I guess that would make GET out of the way, or is there a workaround

There is no maximum URL length defined by the HTTP standard, though some browsers impose one. This probably doesn't matter when generating GET requests via JavaScript, but if you're seriously concerned about it you probably should rethink your API. GET requests shouldn't be sending that much data to the server.

4. The only problem I'm seeing with POST (and which I'm guessing is why a site like twitter went with GET) is that the request can't be made directly from the browser. Correct me if I'm wrong on this.

Your browser can generate POST requests just as easily as GET requests, it's simply harder to submit POST requests via the address bar.