6 ms·

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 th

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.

arethuza 13y ago
"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....
- steveklabnik 13y ago
  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"...
  - arethuza 13y ago
    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 :-)
mattmanser 13y ago
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
- steveklabnik 13y ago
  All I'll say is this: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1.1 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-25#section-4.2.1 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.
  - zimbatm 13y ago
    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.
    - steveklabnik 13y ago
      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.
      - danbruc 13y ago
        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.

arethuza 13y ago

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

steveklabnik 13y ago
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"...
- arethuza 13y ago
  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 :-)

mattmanser 13y ago

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

steveklabnik 13y ago
All I'll say is this: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1.1 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-25#section-4.2.1 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.
- zimbatm 13y ago
  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.
  - steveklabnik 13y ago
    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.
    - danbruc 13y ago
      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.