Thanks bko, that is indeed very good reading. (Your tutorials have also been very good reading, by the way! Used them a lot when I was getting started.) A key constraint of a RESTful API is that a GET request should not change a resource on the server.
So here’s a question: Is Spark giving us developers a framework for designing a RESTful API, or is Spark a RESTful API itself?
Most people would say the latter, Spark is a RESTful API. I here’s the case for the position that Spark is actually a framework for developers to create APIs: we have control over the URL, the parameters to be submitted, and the code to execute when the API calls are made.
So I think it is perfectly reasonable that Spark give us a system for designing a RESTful API with a bit more flexibility for us as developers. In this case, it would be fine for code to be executed on our Spark Cores from a GET request. It would be up to us, the developers, the API designers, to make sure that in this case resources are not being changed from GET requests. Let us, the developers, pick whether each API call is GET or POST based on whether resource state is being changed.
I know, I know, this will allow users making non fully REST compliant APIs where GET requests modify resources on the server (Spark Core). I admit that I would immediately make a non-compliant REST API and use GET requests to change server state.
Moors7 made some very good points about encouraging good practices for developers, and is right that we don’t want to encourage bad behaviour. So, let’s look at this closely: how bad is this behaviour?
To answer this, we need to look at what the harm is in allowing GET requests to change resource states. What’s the advantage of POST in a case where you are changing the resource’s state in some way?
From what I can see, there are two key cases where there is an advantage to POST over GET when changing server resource states:
Resubmitting a POST request could be dangerous. Browsers know this, so they display a warning if you press refresh after a form POST. For example, if code on the other end did actually execute and changed a server resource, but failed to respond. There’s no way of the client knowing what happened, but at least the browser can warn the user that they are about to resubmit the same data. No such warning is displayed when you press refresh on a GET requested page since technically they are not supposed to change each time you request them.
For case number 1, since the Spark API does not return an HTML resource, the browser does not give these types of warning anyways. For many applications, resubmitting the data is actually fine. Remote control is very popular, resubmitting the forward button is perfectly OK. For those cases that it is not OK to resubmit data, it is already up to us developers to implement this warning or other protection. Having the API enforce POST vs GET does not help protect against resubmitting data.
POST cannot be cached, GET can. With GET requests, browsers can skip calling the server if they think they have a fresh copy of the resource already.
For case number 2, there is a HTTP header to specify that GET requests should not be cached. So this automatic behaviour of POST can be applied to easily make GET requests not cache as well. In fact, I had a look at the HTTP headers given to the GET requests for Spark variables, and sure enough, “Cache-Control:max-age=0” is in there, specifying no caching.
I think that when rigidly complying with a specification provides no advantages, and gets in the way of getting things done, you should bend the rules.
I suspect that similar reasoning led to the HTML FORM element allowing the GET method to submit data to the server for processing. There are very few cases where submitting a form full of data is not going to change some resource’s state on the server, and yet there it is, right in the FORM specification. GET is actually even the default, it’s just so much easier a lot of the time than POST.
Many companies have reached this conclusion with their APIs. I have used many APIs over the years that use GET to change server resource states. The Adobe Connect API for example does this:
Changing server resource states with API calls via GET requests is a standard industry practice.
If you want to get totally technical about REST compliance, any API that uses JSON is not RESTful:
One of the key constrains on REST is that a RESTful API must use hypermedia formats (the HATEOAS constraint). Unfortunately, JSON is not a hypermedia format. Source: http://restcookbook.com/Mediatypes/json/
Should we just throw JSON away and never use it? Of course not, we need to send data back and forth, and JSON is a great way to do it, RESTful or not.
So Spark devs, please give us an API framework allowing function calls with GET for an easier way to get work done!