Hacker News Reader

Comment by paul | Hacker News Reader

Fortunately, I don't care.

The broad concepts of REST are good, but this pedantic stuff is so silly. There's a reason that most popular APIs will fail this test -- the people who built them were thinking about more important issues than achieving some kind of religious purity.

View on HN

"There's a reason that most popular APIs will fail this test -- the people who built them were thinking about more important issues than achieving some kind of religious purity."

What issues are those? The article does give reasons for each recommendation that go beyond an appeal to RESTful Authority. I would be curious to hear how the criticized techniques solve some important issue better than the article's recommendation. For example, is there a specific reason that API tokens are better than Digest authentication?

Perhaps creating real business value.

Hi, I'm the original author.

Those people weren't "thinking about more important issues", they were being lazy (or just copying what was being done already, without thinking about why). Its akin to javascript before ajax an jQuery, before we knew any better, we just copy and pasted code off the internet that worked, without spending the time to discover there might be a better way.

Because people are "thinking about more important issues", they're making it harder for consumers to write clients of their API, and they're presenting themselves with unmaintainable web services in the future.

In your article, you listed the following scenarios in which someone would be sad they did things the wrong way:

- Changing the URIs of some resources in order to load-balance across servers, which is a lot easier if clients get those URIs via hypertext instead of from the protocol spec.

- Screwing up user authentication when you could have just used digest authentication.

- Having your service run really slowly because you can't just use Varnish to cache the cacheable parts. (Maybe you didn't actually say this.)

I can't actually find any others in your article. This discussion thread has added a couple more:

- Getting HTTP error codes from an intermediate proxy server instead of from the intended origin server, which will make you wish you had used those HTTP error codes to indicate errors in your app, so that clients would handle them correctly. (There are a lot of ways proxy servers can get involved.)

- Having random robots (Google Web Accelerator, web crawlers, etc.) trash your database by GETting URLs that have destructive side effects.

- Having people not able to explore your API with their browser.

What are the other scenarios?

Most APIs are not restful because their designers had more important issues - Would you say the same for most web pages breaking web stanards or is that another matter entirely?

It's more like using tables instead of CSS -- the only real compliance with web standards here is valid vs. invalid use of HTTP; everything layered on top of that is mostly subjective in the case of REST dogma. In fact, some of the things in this article directly contradict recommendations in O'Reilly's RESTful Web Services.

First author of HTTP 1.1 is Roy Fielding, same guy who defined REST. In fact, http 1.1 was designed largely to make HTTP restful. As such, you'd be surprise how far HTTP goes towards RESTfulness. For instance the spec defines idempotency and satfety of methods. Ergo, servers may produce valid requests and responses but still fail when it comes to being valid http if their internal operation does not conform to the operation semantics. Look up the google web accelerator fiasco to see how things can go terribly wrong.

To be clear, the Google Web Accelerator fiasco was not related to anything Google did wrong with Web Accelerator. It was a result of other people doing things wrong.

Certainly there's a reason, but that's not it. The reason is generally that they were doing what was most convenient at the moment. There are occasional cases where someone was actually thinking about some requirement that conflicted with the REST architectural style, or had an application where the benefits of REST didn't matter. But the much more common case is that someone just wasn't thinking about REST, usually because they don't know REST.

So when API designers do something like define their own status codes and numeric error codes[1] instead of using the universally-known response codes built in to HTTP, is that solving some "more important issue" or is it just adding more work for clients because of a not-invented-here attitude?

1. http://posterous.com/api/reading

What's the HTTP error code for "address didn't match" or "over credit limit"?

(honest question, not snark) - How do you handle application specific messages and errors using the normal http error codes?

Not sure what you mean by "address didn't match" but it would likely be 404 or 403 depending on what the "address" is.

"Over credit limit" would be "402 Payment Required."

You can always return additional, application-specific details in the body of the error response. But choosing a correct HTTP status code is an important first step because it has well-defined semantics (e.g. caching behavior) for client libraries or proxy software that know nothing about your application, and it allows the client to use a single code-path for all error handling.

I was picking on the Posterous API because each response has up to three "statuses" - the HTTP status code, the rsp@stat attribute, and the rsp/err@code attribute. The docs don't even mention what combinations of HTTP status code and response body are valid. (Will errors be served as 200 OK? Will some responses have 4XX or 5XX status codes but not have an "err" element in the body?)

As it is, Posterous clients may need to handle a 200 response with an error in the body, an error response with an error in the body, and an error response without an error in the body (which is not documented in the spec but probably can't be ruled out). Not all client writers will think of all these cases, and not all will handle them the same. It would be better for the API to define its behavior in terms of HTTP, which would put all error handling in a single place.

and an error response without an error in the body (which is not documented in the spec but probably can't be ruled out).

Yes, it's probably more or less guaranteed that if you're hitting Posterous's API through proxies (your own local proxy; your ISP's transparent proxy, if you're not in the US and/or make a bad choice of ISP; the proxy in your company's firewall; a reverse proxy deployed on Posterous's side) that proxy will sometimes generate error messages without any knowledge of what Posterous may or may not have documented.

I haven't read Posterous's spec, maybe they have some way of preventing this, like requiring SSL.

Having a more specific error code/description in the body of the response is fine, it's using yours instead of HTTP's that's a problem. In the Posterous example that was linked, "Invalid site id" sounds a lot like 404, "User does not have access to this site" sounds a lot like 401 or 403, etc.

I agree. For most web services, the REST purity test is unnecessary.

My only point of agreement with the author is that web services that aren't RESTful shouldn't describe themselves as RESTful.

I really hate it when technical discussions devolve into accusations of "religion". You're basically saying that there is no possible rational reason to do things in some way; after that, any disagreement is merely apologetics. What's left to discuss?

Reply on news.ycombinator.com