Hacker News Reader

Comment by handelaar | Hacker News Reader

tl;dr - APIs are necessary and are not a lie, contrary to the first thousand-or-so words of the article, but the author would prefer you had API resources at the same URIs as your user-facing web content, and allow user agents to switch between them using the 'Accept' http header.

View on HN

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.

/end rant about REST

All I'll say is this:

http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1...

Or, if you'd prefer, the almost finished httpbis:

http://tools.ietf.org/html/draft-ietf-httpbis-p2-semantics-2...

  > 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.

alphadogg, you have been hellbanned for more than 2 years.

At this point, I'd just like to inject that looking anything across a network as a function call is probably not a good idea.

Yes, RESTful requests end up in a big-ass state machine like that: https://raw.github.com/wiki/basho/webmachine/images/http-hea... It's great because it allows for a great diversity of clients. In exchange the system is much more complex.

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.

Yup, there's that one, but it also means that you model your application logic as a state machine...

What alternative, preferably HTTP based, would you recommend instead? Going back to SOAP or some custom XML-over-HTTP implementation?

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.

JSON-RPC can run over HTTP and is very old-school in its usage pattern.

Google has some of the worst APIs I've ever seen.

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 would be brutal.

REST is not really an API -- it's basically a basic resource providing mechanism for the Web-centric world; what RDBs are to centralized applications.

You can always have a look at Stripe's API which is great and take inspiration from there - https://stripe.com/docs/api

> So why on earth would you use that very bad library design

Because when you design a Web API you're not designing a library, you're designing part of a distributed system.

Accessing code on a remote server is not like accessing code in a DLL, and never will be.

That was just an example.

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.

Everyone who blabs about rest, including my boss, reminds me of 'reactive' programmers and the "fire and motion" article:

http://www.joelonsoftware.com/articles/fog0000000339.html

"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?"

>>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.

"the author would prefer you had API resources at the same URIs as your user-facing web content"

I thought one of the principles of RESTful design is that the internal structure of URLs shouldn't really matter - you should be able to navigate to any resource from being given a single base URL. So i struggle to see what difference it makes if RESTful API consumers see different URLs to browser users....

It's because your parent is making a different claim than the author. The author is saying that you shouldn't be running two different services to expose the exact same data, which is not the same claim as "your API has the same URLs as your web content."

A lot of this comes down to what you mean by "API"...

I guess that's what I get for believing a tl;dr - I did skim the article but thought it was a bit ranty for me to be bothered to read in detail :-)

Reply on news.ycombinator.com