5 ms·

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 tes

by paul 17y ago

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.

credo 17y ago
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.
alexandros 17y ago
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?
- wheels 17y ago
  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.
  - alexandros 17y ago
    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.
    - kragen 17y ago
      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.
kragen 17y ago
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.
jimbokun 17y ago
"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?
- bsaunder 17y ago
  Perhaps creating real business value.
mbrubeck 17y ago
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 http://posterous.com/api/reading
- cschneid 17y ago
  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?
  - mbrubeck 17y ago
    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.
    - kragen 17y ago
psadauskas 17y ago
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.
- kragen 17y ago
  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?
bct 17y ago
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?

by paul 17y ago

credo 17y ago

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.

alexandros 17y ago

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?

wheels 17y ago
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.
- alexandros 17y ago
  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.
  - kragen 17y ago
    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.

kragen 17y ago

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.

jimbokun 17y ago

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

bsaunder 17y ago
Perhaps creating real business value.

mbrubeck 17y ago

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 http://posterous.com/api/reading

cschneid 17y ago
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?
- mbrubeck 17y ago
  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.
  - kragen 17y ago

psadauskas 17y ago

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.

kragen 17y ago
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?

bct 17y ago

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?