Which in fact is a massive headache, incredibly complicated and you'll wish you hadn't.
/start rant about REST
I'm also sick of people believing that REST is some magic pancea to the API problem.
Go look over any project you did before you heard of REST. Did you just have 4 methods on your objects called Get, Create, Update, Delete? With loads of extra parameters you can optionally pass in?
Do you think that would make a good API for an actual library?
No, of course not.
So why on earth would you use that very bad library design just because it's going over HTTP? HTTP was meant for documents, not programming APIs.
RESTful APIs was always a stupid idea. And don't even get me started about the nonsense that a GET doesn't modify anything, of course it does to even the most basic objects, I just logged your access to it. I may have checked whether you were logged in and updated your last access time. The amount of views that object has has just increased. The system changed in many different ways, possibly including the object.
I'm tired of APIs that try and contort a complicated API into some crazy REST structure by using loads of parameters. Google, I'm looking at you. You guys are smart programmers, how have you not realized the entire concept is intellectually vapid.
> This definition of safe methods does not prevent an implementation
> from including behavior that is potentially harmful, not entirely
> read-only, or which causes side-effects while invoking a safe method.
> What is important, however, is that the client did not request that
> additional behavior and cannot be held accountable for it. For
> example, most servers append request information to access log files
> at the completion of every response, regardless of the method, and
> that is considered safe even though the log storage might become full
> and crash the server. Likewise, a safe request initiated by
> selecting an advertisement on the Web will often have the side-effect
> of charging an advertising account.
I'd suggest that you become more informed about something before having such strong feelings about it.
You have variants in:
the HTTP method, the URL path, the URL query params, various HTTP Headers (cookie, content-encoding, content-language, ...), the Body (with various forms of content encoding) , did I miss something ?
If you think of a request as a function call then it's all parameters and it's completely crazy.
Yup. That's why requests aren't function calls. REST is a different architecture than RPC, which is why you need all of these conventions to do RPC over HTTP: you're mapping one architecture onto another.
A HTTP request is a function call. A function call is message passing. No matter if you use RPC, SOAP or what not. It's conceptually all the same - the caller sends a message to the callee which responds with another message.
Yes, if you map the concepts over. Which is what you just did. The RESTful architecture is explicitly _not_about function calls. It's about manipulating state diagrams. Yes, you do that through a message, but it's different than a function call, unless you define 'function' and 'message' in a way that's completely meaningless. If any message is a function call, a UDP packet is a function call.
If you can require your client to behave in a normalized way then all this complexity is not necessary and you're probably avoiding some bugs along the way.
No wonder you hate REST HTTP APIs. Take a look at FreshBooks API. They have a more complicated application (in terms of model complexity and ACL complexity, not scale) than most of Google APIs and besides the fact that they only support XML, their API is really fucking good. It is unsurprising and it it's been around a good long while.
Would you really rather FreshBooks use an RPC API? /setup_payment_for_invoice
/pay_payment_on_invoice
/allow_contractor_to_submit_expenses
/create_new_time_tracked_amount
It's a computer asking for an action talking to a computer asking for an action.
Call them whatever you want, the concept is extremely simple and pretending it's anything more complicated is obfuscating the underlying simplicity of the intent of the programmer. i.e. I want the other computer to do something or the other computer to send this computer some information.
The intent is simple, but there are many ways to express that intent. Some of them work well when there are two components sitting right next to each other in memory on one machine; others work well for an unknown number of components interacting with each other over a slow, unreliable network.
Even if RPC is a fundamentally, unambiguously simpler way to express that intent (and I think that's arguable), it does not meet the same technical requirements that REST does.
>>And don't even get me started about the nonsense that a GET doesn't modify anything
It is not nonsense. It is a very useful convention. If you stick to it, you get some system properties ... for example, you can very easily put a caching layer (nginx, varnish, etc ...) which can reduce a huge amount of load to your backends, without worrying that it will change the behaviour of your backend.
"People get worried about .NET and decide to rewrite their whole architecture for .NET because they think they have to. Microsoft is shooting at you, and it's just cover fire so that they can move forward and you can't, because this is how the game is played, Bubby. Are you going to support Hailstorm? SOAP? RDF? Are you supporting it because your customers need it, or because someone is firing at you and you feel like you have to respond?"
This "API over HTTP" stuff is something I've been noodling on for awhile. If you've got some suggestions for, I don't know, "RPC over HTTP" or just exposing typical library calls over HTTP (neither involving SOAP, please, dear $DEITY...) I'd personally be interested in reading them.
And as I write this and think on it a bit more, I'm realizing that 'serializing' APIs over HTTP probably isn't the best idea in the world. But it makes things "easier" - firewalls don't need configuration to let your customers access your remote API, HTTP traffic tends toward human-readable text, etc.
/start rant about REST
I'm also sick of people believing that REST is some magic pancea to the API problem.
Go look over any project you did before you heard of REST. Did you just have 4 methods on your objects called Get, Create, Update, Delete? With loads of extra parameters you can optionally pass in?
Do you think that would make a good API for an actual library?
No, of course not.
So why on earth would you use that very bad library design just because it's going over HTTP? HTTP was meant for documents, not programming APIs.
RESTful APIs was always a stupid idea. And don't even get me started about the nonsense that a GET doesn't modify anything, of course it does to even the most basic objects, I just logged your access to it. I may have checked whether you were logged in and updated your last access time. The amount of views that object has has just increased. The system changed in many different ways, possibly including the object.
I'm tired of APIs that try and contort a complicated API into some crazy REST structure by using loads of parameters. Google, I'm looking at you. You guys are smart programmers, how have you not realized the entire concept is intellectually vapid.
/end rant about REST