3 ms·

The epiphany we had was that whilst machines do access the API, the developer is always the customer and user. Everything we do should help the develope

by h2s 13y ago

The epiphany we had was that whilst machines do access the API, the developer is always the customer and user. Everything we do should help the developer, and if we have to break rules to help them... then largely we should. Thank you, this articulates my disagreement with the idea of hashing all URLs so that client developers are forced to follow links returned by the API instead of generating their own URLs http://blog.ploeh.dk/2013/05/01/rest-lesson-learned-avoid-hackable-urls/ http://blog.ploeh.dk/2013/05/01/rest-lesson-learned-avoid-ha...

just2n 13y ago
There's nothing really wrong with RPC-like APIs. They're often much simpler to use in modern web development, for developers with access to documentation. Hyperlinking has a few benefits, the biggest being discoverability without the need for browsing some documentation that explains how to build URLs, but it's not always the best possible solution for every application -- and it typically leads to chatty applications. The only thing that bothers me, though, is when these RPC APIs are called "RESTful" just because they use HTTP verbs correctly.
- sopooneo 13y ago
  This speaks to something that has baffled me for a long time. If we have to bend/break the rules of REST to make things usable in the real world (and I believe we do), why have REST as an ideal in the first place? Why work halfway towards A, when we could define a more realistic B and implement it fully? We spend too much time justifying which parts of the holy book to ignore.
  - steveklabnik 13y ago
    You have different objectives than a purely RESTful system does. If you had REST's objectives in mind, then the architectural constraints would be sensible.
    - sopooneo 13y ago
      But who has truly RESTful objectives in mind? Are there any widely used REST APIs that truly adhere? I acknowledge that there may be. It's just the ones I come across always make significant concessions. Sometimes people tell me that "the web as a whole" or RSS are examples, but those seem too fundamentally different from any API I might create.
      - steveklabnik 13y ago
        The GitHub API is pretty damn close these days, and I can tell you that there's a very big company you've heard of with a two-digit person team working on a HAL-based hypermedia API right now. Twilio has been pretty good too. There are lots of private APIs that operate this way; for example, much of Comcast's internal stuff is pure, hypermedia driven REST. But it's not open source, so you don't hear about it. A YC-funded company, Balanced Payments, does an excellent job as well. > those seem too fundamentally different from any API I might create. Right! That's because you're primarily thinking of RPC styles, so of course it will seem foreign. Try this sentence on for size, from a different time period: "But who has truly object oriented objectives in mind? Some people tell me that Smalltalk or C++ are examples, but those seem too fundamentally different from any code I might write." That's not to say RPC is a bad thing: often times, it's just fine. But if you have the problems REST is designed to solve, REST will solve them much better.
wnight 13y ago
The blog you linked seems to miss the point. (Which I think is what you're saying.) If people try to guess URLs for what you see as (for example) steps 3-7 of a ten-step process, maybe you should see what your users are trying to tell you - that it's at least three smaller tasks that need to be usable individually. And if there really is some reason to force them to use your workflow (perhaps you want to push ads in step 2 and not release content until your javascript sends home a message saying the ad is visible) then you need to do it right and give them an unforgeable token, or make note of an existing unforgeable token - ie what a cookie is for. This is what the obfuscated URLs are (something unforgeable) but this fact of their nature mainly makes debugging harder - for third-party developers and for the primary developers. This is an example of the problem of the non-experts re-inventing security. At best this matches existing common practices for user-auth, at likely worst it's worthless and you'll never know it because you can't debug it. So yeah, I think I agree. Hashing URLs for some sense of control over how they're used misses the boat on security and wastes all the benefit of human-readable protocols, etc.
nahname 13y ago
The other benefit of defining the endpoint in the resource is that you can send the request somewhere else. Sharding your API, so to speak.

by h2s 13y ago

just2n 13y ago

There's nothing really wrong with RPC-like APIs. They're often much simpler to use in modern web development, for developers with access to documentation. Hyperlinking has a few benefits, the biggest being discoverability without the need for browsing some documentation that explains how to build URLs, but it's not always the best possible solution for every application -- and it typically leads to chatty applications. The only thing that bothers me, though, is when these RPC APIs are called "RESTful" just because they use HTTP verbs correctly.

sopooneo 13y ago
This speaks to something that has baffled me for a long time. If we have to bend/break the rules of REST to make things usable in the real world (and I believe we do), why have REST as an ideal in the first place? Why work halfway towards A, when we could define a more realistic B and implement it fully? We spend too much time justifying which parts of the holy book to ignore.
- steveklabnik 13y ago
  You have different objectives than a purely RESTful system does. If you had REST's objectives in mind, then the architectural constraints would be sensible.
  - sopooneo 13y ago
    But who has truly RESTful objectives in mind? Are there any widely used REST APIs that truly adhere? I acknowledge that there may be. It's just the ones I come across always make significant concessions. Sometimes people tell me that "the web as a whole" or RSS are examples, but those seem too fundamentally different from any API I might create.
    - steveklabnik 13y ago
      The GitHub API is pretty damn close these days, and I can tell you that there's a very big company you've heard of with a two-digit person team working on a HAL-based hypermedia API right now. Twilio has been pretty good too. There are lots of private APIs that operate this way; for example, much of Comcast's internal stuff is pure, hypermedia driven REST. But it's not open source, so you don't hear about it. A YC-funded company, Balanced Payments, does an excellent job as well. > those seem too fundamentally different from any API I might create. Right! That's because you're primarily thinking of RPC styles, so of course it will seem foreign. Try this sentence on for size, from a different time period: "But who has truly object oriented objectives in mind? Some people tell me that Smalltalk or C++ are examples, but those seem too fundamentally different from any code I might write." That's not to say RPC is a bad thing: often times, it's just fine. But if you have the problems REST is designed to solve, REST will solve them much better.

wnight 13y ago

The blog you linked seems to miss the point. (Which I think is what you're saying.) If people try to guess URLs for what you see as (for example) steps 3-7 of a ten-step process, maybe you should see what your users are trying to tell you - that it's at least three smaller tasks that need to be usable individually. And if there really is some reason to force them to use your workflow (perhaps you want to push ads in step 2 and not release content until your javascript sends home a message saying the ad is visible) then you need to do it right and give them an unforgeable token, or make note of an existing unforgeable token - ie what a cookie is for. This is what the obfuscated URLs are (something unforgeable) but this fact of their nature mainly makes debugging harder - for third-party developers and for the primary developers. This is an example of the problem of the non-experts re-inventing security. At best this matches existing common practices for user-auth, at likely worst it's worthless and you'll never know it because you can't debug it. So yeah, I think I agree. Hashing URLs for some sense of control over how they're used misses the boat on security and wastes all the benefit of human-readable protocols, etc.

nahname 13y ago

The other benefit of defining the endpoint in the resource is that you can send the request somewhere else. Sharding your API, so to speak.