I am researching before starting to work on an API for a web-service I am building. The goal is to be very quick and easy to adapt and use for other developers but fairly hidden for clients using a collection of Webapps to make calls to the service behind the API.
It is the first time making an API for more than internal use and I am now wondering researching the standards out there if I should follow RESTful recommendations or rather just go (my instinct) with POST Requests and a JSON-body that holds all the necessary information.
My reasoning against using GET / HTTP-Verbs:
- The service has fairly fine grained Read/Write control for every single User and DB items. So even a simple LIST request has to be checked not only for credentials but has to do a bunch of internal validation procedures to see if the client is allowed to ask this questions for this particular piece of data.
- easy implementation: while coding I usually am happy to not have to hop between GET Urls and POST or PUT bodies to get my JSON payload over the line. Appending them to the URL if it is a GET request or into the body if it is a POST or a PUT. So it feels less of a hassle to just go with POST. but I see that is very much my personal taste rather than true for everybody – I am just damn lazy 😉
- not really a valid point because we use SSL anyhow, but https://stackoverflow.com/questions/198462/is-either-get-or-post-more-secure-than-the-other#1744404 suggests that it at least, in theory, it might be a little more secure to not force too much sensitive stuff into the URL. In particular, if even READ/LIST requests are considered sensitive for a service, it feels at least a little weird to operate within the URL.
my reasoning for using GET / HTTP-Verbs:
- Compatibility: Standards are great. And RESTful APIs still seem the most common ones.
GET can be easily tested or used by clients from a browser (not sure if that is really a plus, but it might turn out as one) - RESTful forces me into a fine-grained separation of concerns through not only URL but also the HTTP verbs (GET/POST/PUT etc). Only using POST I could do the same through URL or early JSON parsing.
- this blogpost explains a bit about the issues, I found very helpful
Are there any other strong reasons for using the full variety of HTTP verbs like for example REST principles would suggest?
I cannot find any API that does not use different HTTP Verbs. So I guess there must be very strong reasons for that. I suspect the reasons mentioned in the blogpost to be the most relevant, but wonder if there is more to it and if there are other solutions than the one proposed there (first POST, then serving a new GETable resource and returning the URL)
note
this question is similar to mine but comes from a slightly different angle: Is it bad to use POST only on an API?
Best Answer
"What reasons are there AGAINST using only POST HTTP verb in an API?"
You have answered your own question:
If your goal is for other developers to quickly understand and use your API, then use generally accepted practices that most developers would expect. It's as simple as that.
To review your reasons for using POST:
If you want to experiment with an API that only you will ever use, then feel free to do whatever you wish. But if you want other developers to use it then please save us the frustration and just use the standards.