[pixie_]

I don't like REST. Making a call to a server should be like calling a function anywhere else - you have your parameters and return value. In REST the parameters are spread over 3 places, the action, the url and the post parameters themselves. It's a much better design to combine all your parameters in one place and keep things simple, for example -

REST version: UPDATE /course/324234 { description: "This is a level 1 course" }

Improved version: POST /course/UpdateDescription { courseId: 324234, description: "This is a level 2 course" }

In this case POST is always used for api calls. Course is the namespace, UpdateDesciption is the method name, and parameters are kept all together as JSON.

[enjo]

The REST version makes it clear that you are dealing with operations on a resource. The URL identifies a thing in a consistent way, while the method and corresponding data allow you to manipulate it.

The biggest benefit comes when building a cache architecture. RESTful API's (when properly implemented) come with built-in assumptions about idempotency. You end up in a place where you can easily cache GET requests while reasoning in a very consistent way about where changes to a resource will be made.

It's a pattern that comes with a lot of really useful benefits.

Now all of those same qualities can be built into other architectural styles (such as the one you propose). However, I find that it becomes much harder to reason about the role of operations and what they're actually doing when you lose that clear distinction that REST enforces.

I do want to quibble with one thing as well:

In REST the parameters are spread over 3 places, the action, the url and the post parameters themselves

That's true for any modular system isn't it? You have the object you are operating on, you have the operation, and you have the data. Object-oriented systems and even most structured languages (like Javascript for instance) make this distinction at some level. Why is that not appropriate for web architecture?

[pixie_]

Just because something is GET doesn't mean it can be cached. It's not consistent, and every API call needs to be evaluated individually. The thing with REST is that it treats all functions as a variant of a CRUD operation, while functions may do more than just CRUD or a combination of CRUD operations in a single API call. Imagine if all your javascript functions had to be prefixed with GET/UPDATE/DELETE/etc.. you would feel constricted, and for what reason? Imagine if your function names had data in the call path MyCourse.32423.Delete(); that doesn't look very good does it? 32423 would look alot better inside Delete().

[enjo]

GET requests, by definition, should have no side-effects. Which makes them cacheable. Many browsers cache GET requests by default unless cache-control tells them not to.

You can most definitely write a GET request that contains side-effects, but that's because you're doing it wrong (tm).

Imagine if your function names had data in the call path MyCourse.32423.Delete(); that doesn't look very good does it? 32423 would look alot better inside Delete().

That's not data, that's an object. "MyCourse.32423" is the actual resource. It would actually look something more like:

MyCourse32423.Delete();

Which seems pretty reasonable to me if we're trying to map this into programming language semantics (which I'm not even sure we should be doing).

[Domenic_S]

I cringe a little bit whenever someone tries to present caching as simple or straightforward.

[drivebyacct2]

I don't see that anywhere in the post. All I saw was "GET"s shouldn't modify state and should be cacheable. That seems perfectly in line with the spec.

[jebblue]

The only problem I have with your comment is that REST is not specified, it's a style:

http://en.wikipedia.org/wiki/Representational_state_transfer

[SilasX]

>It's a pattern that comes with a lot of really useful benefits.

Sure, but people can implement that pattern without buying into the whole clumsy REST edifice.

For example, a strict reading of REST (and RESTers support such readings!) would tell me that if I have an API that takes two cities and returns the distance between them, then I must expose a URI pointing to every combination of cities.

See here: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...

>>A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) ... From that point on, all application state transitions must be driven by client selection of server-provided choices that are present in the received representations or implied by the user’s manipulation of those representations. ... [Failure here implies that out-of-band information is driving interaction instead of hypertext.] [emphasis mine]

So, 1000 cities, you must send a million links over the network rather than 1000 possible parameters plus the formatting.

Now, some RESTers assure me that, no, you can somehow communicate to the user that [prefix] / [first city] / [second city] will get you that answer; that a server can "instruct clients on how to construct appropriate URIs".

Fine, but then we're right back to custom, author-documented APIs and RPCs: "to do that, format the call this way". Right back where we were before trying to force-fit everything into a CRUD mold with increasingly bizarre tables just to make all the calls work.

Or maybe a REST purist would tell me that I'm supposed to link a URI for the starting city: [root]/distances/[start city]/, and then from there link them to possible choices of the second city: [root]/distances/[start city]/[end city]/ .

Fine, but why jump through two pointless hoops, when I know what I want, and I prefer to just send one request rather than pointlessly spend bandwidth navigating a path I don't care for?

[bct]

> 1. [send a link for each possible combination]

> 2. instruct clients on how to construct appropriate URIs

> 3. link a URI for the starting city and then from there link them to possible choices of the second city

All three of these are possible RESTful solutions, and I can imagine situations where each of them might make sense.

But what you're probably looking for is something like this:

  <form><select name="city1">...</select><select name="city2">...</select></form>

(Using URL templates is a potentially simpler way to achieve the same thing). This is, of course, your solution 2.

There are tradeoffs involved in using this style. Are they worth it? That really depends on the larger system and all kinds of details which you've left out.

[SilasX]

That is not a RESTful solution, though: what resource is it acting on? What are the four CRUD operations for it?

You have to come up with some added, unnecessary, implementation-exposing abstraction like "CityPair". (In which case "delete" could be ill-defined if, as would be wise, the distance is computed from a lat/long or road table lookup, and so there is no actual database entry that corresponds to the distance between the cities.) That's the problem with REST: it doesn't avoid the complexity of RPC; it just crams it into ever-more-creative resource types.

Most API users (sorry, "consumers") would prefer they just be told the format in which to ask for the data, not have to re-discover it through gradually-exposed paths each time.

[bct]

> what resource is it acting on?

The distance between the two cities.

> You have to come up with some added, unnecessary, implementation-exposing abstraction like "CityPair".

This is a really weird thing to say. No, you don't. I have no idea why you would think that.

> What are the four CRUD operations for it? [...] In which case "delete" could be ill-defined

Not every method has to be valid for every resource. It's a total non-issue that you can't delete a distance.

(And POST/GET/PUT/DELETE is a very different concept from CRUD.)

[SilasX]

>>what resource is it acting on?

>The distance between the two cities.

Don't be cute. What server resource is it acting on? The value of the distances is (potentially) computed by some encapsulated algorithm -- you're not acting on that resource. The server resources that are touched are the two cities, and then whatever it does behind the scenes.

>This is a really weird thing to say. No, you don't. I have no idea why you would think that.

Because I'm not GETing a city, so I can't use the GET operation on the city resource; I have to make another resource to GET. Fine, it doesn't have to be a city pair: but there is a many-to-many mapping, which in REST-favoring frameworks (e.g. Rails), requires a separate table. By reducing everything to CRUD, you must create a new resource (type) for each new operation.

>(And POST/GET/PUT/DELETE is a very different concept from CRUD.)

That's a non-standard definition of "very different", considering that POST is create, GET is retrieve, PUT is update, and DELETE is delete.

[bct]

Nobody ever said that you should use REST if it doesn't suit the problem you're trying to solve.

[SilasX]

But there are people that believe REST suits every API problem, even when accumulated wisdom says it doesn't suit the problem (cough Roy Fielding).

[bct]

No, he makes it quite clear that it's a solution designed for a particular problem space. You're debating a straw man.

[SilasX]

Indeed: the problem space being APIs. Feel free to point me to an example of fielding pointing to an API problem that shouldn't be RESTful.

[andrewflnr]

Part of the debate is what problems REST is suited to solve. While most evangelists will never come out and say, "you should use X for everything," they will try to fit it into whatever situation it will "reasonably" fit into, which is probably a bigger domain than the problems it's "best" for.

[bct]

The thesis lays out in detail what REST provides:

"REST provides a set of architectural constraints that, when applied as a whole, emphasizes scalability of component interactions, generality of interfaces, independent deployment of components, and intermediary components to reduce interaction latency, enforce security, and encapsulate legacy systems."

The existence of these properties should be fairly evident when you examine the constraints.

I think large part of the confusion comes from not recognizing the difference between "Any system can be built in a RESTful style" (this is true) and "Every system should be built in a RESTful style" (this is a straw man).

[ProblemFactory]

That tagline may explain the benefits of REST, but it doesn't really explain at all which problems REST is well-suited for and which not.

I've found that REST design is great for problems where the most visible abstraction is a document or an object (with operations or functions as secondary). It doesn't really fit problems where the most common abstraction is a function call (with the arguments a secondary concern).

[pbreit]

Not true.

GET /distance?cities=San+Francisco,Los+Angeles would suffice. city1=modesto&city2=fresno might be preferred if you wanted to support form submissions, too.

Query strings are perfectly restful.

[SilasX]

That just shows it's HTTPful, not RESTful. In this case, that protocol involves being told how to construct a URI rather than it being presented from a menu of choices discovered by following URIs in the API.

I agree that it's much more convenient to have well-defined fill-in-the-blank. I disagree that it matches the requirements of REST, whose proponents always tell me "If you document the URIs or how to build them, you're doing it wrong."

http://stackoverflow.com/questions/1164154/is-that-rest-api-...

[bct]

> involves being told how to construct a URI

The crucial thing that you're missing is that it's being told how to construct that URI in-band. Not in a piece of documentation that has to be hard-coded into the client.

[SilasX]

So, once again, it turns out that REST reduces to RPC plus some advisable practices as soon as you point out how the original REST schema is woefully impractical.

Not-REST: You can algorithmically generate requests for the information you want based on documentation.

REST: You can algorithmically generate requests for the information you want based on documentation that's provided in the session. (Oh, and forget all that crap we said about URIs having to be presented to the API consumer as part of session's hyperlink navigation.)

So, now I can turn RPC into REST just by slapping a link to the documentation on every response (and maybe moving verbs to the appropriate HTTP request type, even though that has nothing to do with CRUD[1])? Gee, why didn't you say so?

[1] http://news.ycombinator.com/item?id=4811969

[pbreit]

If thats truly required (i dont think it is), the second example could be shown via introspection.

[benatkin]

> Making a call to a server should be like calling a function anywhere else - you have your parameters and return value.

What you've described is RPC, which has been around for ages. Why do you think REST became a popular alternative to RPC?

[makmanalp]

Because the de-facto transport for it is HTTP, which a) People know b) Is simple and predictable c) Has had support from every language on the face of the earth, for ages and thus d) Takes 1 minute to get up and running with, as opposed to, say, SOAP etc. e) Fits the CRUD model fairly nicely, which comprises the majority of web apps.

Nothing to do with one man's phd thesis or anything (that came YEARS after he wrote the HTTP spec and after most RPC systems). If I had a penny for all the theses that proposed something reasonable which was ignored.

[josephlord]

You missed: gets through proxies and firewalls.

Unless that is what you mean by (b).

[smacktoward]

Congratulations, you just invented JSON-RPC (http://www.jsonrpc.org/).

[pixie_]

I'm not saying how the parameters or return values should be formatted other than the fact they're in JSON format. JSON-RPC requires you to conform to their specifications.

[bct]

APIs that ignore the realities of distributed computing and that each have different special-snowflake wire formats requiring tedious documentation: the worst of both worlds.

[pixie_]

I'm not arguing against implementing an RPC if that's what you need. My original post describes a super set of JSON-RPC.

[drivebyacct2]

Your post implies a pseudo-free-for-all and defeats the purpose of having a conversation about a standard exchange format.

You basically have said "I want to make it work the way I want it and I don't care if it's non-standard and unintuitive.". You're welcome to do that, but everyone who needs to work with it will hate you. And when you've been working on it for 2 months, or take a two month break, you'll come back and hate yourself too...

[biot]

If your course has 20 member variables, now you have 20 update methods? If you want to update multiple, the client then needs to do multiple round-trip calls to your API which is time-consuming: if it's a 350ms round-trip per call, updating all 20 fields takes 7 seconds. And unless you go out of your way to offer per-object locking (which over a stateless connection has its own challenges) you prevent users from doing atomic updates to multiple fields at once. This pushes any rollback mechanism onto the client, exactly where it should not be.

With your design, if your goal is to "combine all the parameters in one place to keep things simple", you could go one step further and have:

POST /course/update {courseId: 1234, field: "description", description: "hello"}

Taking this to its logical extreme, you can truly combine all the parameters in one place:

POST / {object: "course", operation: "update", courseId: 1234, field: "description", description: "hello"}

[pixie_]

Like any other programming language if you need to update multiple fields, you pass multiple parameters to the function. The URL should be equivalent to namespace/class/method while the parameters are just that - parameters you can pass in JSON format.

[MatthewPhillips]

You're putting the burden of learning implementation details of your system onto your customers. That won't be comfortable for either them or you. Should you need to deprecate a method you'll never be able to remove it. So be prepared to write a lot of { "Error": "ErrorCodeThatOnlyMakesSenseInTheContextOfThisAPI", "Description": "DEPRECATED" }

[vyrotek]

I'm with you on this one. Don't get me wrong, I think REST is great too but mostly just because it's something we can agree on.

In the end a route/url maps to a method with parameters anyway. I wish JSON-RPC was a bit more popular. http://www.jsonrpc.org/specification

[bct]

> Making a call to a server should be like calling a function anywhere else

You can make calling a function on a remote machine look and seem (superficially) like calling a local function, but they will never have similar behaviour. A network is very different from a motherboard.

http://www.tbray.org/ongoing/When/200x/2009/05/25/HTTP-and-t...

[scanr]

Here's where I've found REST very useful:

It makes for predictable APIs for consumers and it means API producers have a checklist of things to implement to consider their interface 'complete'. It also provides a consistent way to think about how to expose an interface (or in fact, how to expose entities).

[mixedbit]

IMO the biggest benefit of REST vs RPC is reduced coupling between the client and the server. With RPC client needs to be explicitly aware of all methods and parameters that the server supports. With well designed REST interface this is not the case, you can have a generic client that does not need to be explicitly coded to support the specific service. REST interfaces are more difficult to design than RPC interfaces, but they are also more elegant and simpler. Roy Fielding (REST father) argues that elegant and simpler != easier.

[politician]

Rich Hickey (Clojure) has a presentation about the differences between simple and easy. If you have the time, it's worth it.

http://www.infoq.com/presentations/Simple-Made-Easy

[jaimebuelta]

REST makes useful to be able to do:

- UPDATE/course/324234 - GET /course/324234 - DELETE /course/324234

with predictable results.

Of course, it works better when you have a clear hierarchy of resources, and/or it make sense to do UPDATE/GET/DELETE to the resources with clear results.

I think it works for some cases very well, but I don't think is always the way to go. That said, there are a sensible number of "RESTful APIs" that are not RESTful at all, they just uses HTTP.