The Parley Letter and REST

I’ve just enjoyed reading David’s article named “The Parley Letter”

[http://david.heinemeierhansson.com/2012/the-parley-letter.html](http://david.heinemeierhansson.com/2012/the-parley-letter.html)

Except for the RSpec part, I generally agree with his opinions on

that article and found it a reasonable one.

I just stopped the flow of the read for a moment when I read this

snippet:

"
When I introduced REST as a concept for Rails in 2006, it wasn't

because of the intellectual purity of the prophet Fielding. It was
because the pattern provided real, practical advances for the code
it was applied to. Unweilding controllers gained a perfect straight
jacket in the softest silk to keep them under control. It made the
connection between CRUD and the web in such a way that we could just
take the convention for granted and start worrying about other
things.

So I felt there was a lot there there. Granted, lots of others

didn’t at the time, but today I don’t see a lot of people arguing
against the progress we gained from that…"

In fact, I was one of those who didn't buy the REST argument. And I

still don’t. And I haven’t seen any progress gained by it either.
Lots of people seem to agree with me since I didn’t see other
Rails-like frameworks out there becoming RESTful by default even
many years later after Rails has introduced the idea on Rails 2.

Maybe I could use it if I ever worked in some application that had

the requirements of being externally accessible through some public
HTTP API. But I’ve since then worked in something about 7 big apps
since I started working with Rails in 2007 (not all of them were
Rails ones though, but some were Grails ones instead). All of them
are still actively developed/maintained (although not by me, who am
responsible currently only for a single app since I joined my last
company which has this single app).

I never had a need to support public HTTP based APIs in any of those

apps. I’ve also met other real apps since 2007 and talked to many
devs and the apps they maintained and even helped them sometimes and
I couldn’t find a single app that would benefit from a REST API…

You might ask: "why do you matter?! It is not a big deal. Just don't

use it!". And I’d agree since it never bothered me that a scaffold
generator will generate RESTful controllers/views since I never used
scaffold generated code (except when learning Rails for the first
time) even on Rails 1 era. And when I use the “controller” generator
it generates the controller and the views the way I want them to be
generated. And even if I wanted to generate a non restful scaffold I
could write/use different templates. Then why am I writing all of
this?

Because I don't think a "Getting Started" guide should even mention

REST:

http://guides.rubyonrails.org/getting_started.html

Nevertheless it is exactly in the second chapter (2.3)...

I don't think evangelizing REST makes sense if you read the rest

(interesting word, huh?!) of the article. Or even if you remember
the first articles/talks by David that I used to read by 2007 where
people often talked about developing a framework for 80% of the
applications that are usually built out there. How many of the apps
out there need a REST API? I’d guess less than 10%. Then why
preaching about REST in the Getting Started section of the Rails
guides? I think that guide should be focusing on what is common for
80% of the apps being developed, not by 10% of them…

It seems David has now changed his mind as he no longer talks about

80-20%, but:

"So yes, the closer your application is to an application like

Basecamp – and I make that net extremely wide, I consider, say,
500px, Github, Shopify, and others to fall into “close enough” –
the closer you are to the primary use case that guides the
development of Rails."

While the 80-20% idea makes sense to me, I don't think a popular

framework should be optimized for uncommon applications, like
GitHub, Shopify or Basecamp.

In summary, I'd just like you to consider removing the REST section

from the Getting Started guide or moving it far to the end of that
guide.

Cheers,

Rodrigo.

Hi Rodrigo,

I agree that section is too premature, someone new to Rails can get
started without such an introduction to REST. I definitely would use
the resources macro and do things in an idiomatic way, with idiomatic
routes and actions, but you do not need to introduce the whole
conceptual basis for that.

Would you like to work on a patch?

I'll try to take a look at the rest of the guide tomorrow night (I have a party tonight and I'm working right now). If the rest of the guide doesn't require REST understanding then I'll prepare a patch and send as a pull request (instead of pushing to railsdocs as I'm not sure if it will be accepted and don't want to mess around). Otherwise I'll let you know to understand what is your opinion on what we should do to the rest of the examples in that guide...

Cheers,
Rodrigo.

I am working on re-writing this guide already, but haven't gotten to
this section. I was already planning on doing this. If you want to
write it, go ahead, but I should be taking care of it soon.

I believe we can take HTTP for granted. So, "the HTTP DELETE verb
gets routed to blah" and similar sentences can be used. If the reader
does not know what is the HTTP DELETE verb he can google it, and there
can be a further reading section... But you need to assume something
to base the wording on.

Hi Steve, great news. Then I think it would be better for me not to work on that guide now. When you get it rewritten please let me know and I'll gladly review it.

Best,
Rodrigo.

You could just point to the Routing guide which covers the subject
more in-depth:

http://guides.rubyonrails.org/routing.html

I just find it weird that the section is called "2 Resource Routing:

the Rails Default"

Why "the Rails Default"? It is only used in the scaffold generator,

right? The “controller” generator doesn’t use resourceful routes,
right?

Maybe "default" is not the best word. It is idiomatic, customary,
strongly recommended, etc. (and you do not need to qualify it in a
section title anyway).

/:controller/:action/:id is definitely not going into the getting
started guide so to speak.

Maybe "default" is not the best word. It is idiomatic, customary,
strongly recommended, etc. (and you do not need to qualify it in a
section title anyway).

Why is it strongly recommended?

/:controller/:action/:id is definitely not going into the getting
started guide so to speak.

I agree. I don't use this route either and I also don't think it is a good default, like it used to be in Rails 1 and still is in other Rails-like frameworks.

Hi Steve, great news. Then I think it would be better for me not to work on
that guide now. When you get it rewritten please let me know and I'll gladly
review it.

I plan on submitting it as a PR so that everyone can check it out: as
it's the canonical first introduction to Rails, it'd be inappropriate
for me to commit it without soliciting feedback from everyone.

Rodrigo and Steve,

Ryan Bigg already worked on the Getting Started guide sometime ago and made it a lot simpler. One of the changes was removing the early references to REST - https://github.com/rails/rails/commit/2f06c94e38a116fdfa43d7b7117e6bf911a0bff5

Please check the edge guides to see the latest http://edgeguides.rubyonrails.org/getting_started.html and feel free to make it better :slight_smile:

Thanks

Vijay

:metal:

I am, of course, working off of edge, so it'll be building on what Ryan did. :slight_smile:

Fantastic! Loved the new guide. Congrats, Ryan!

You took off all the magic of Rails from beginners which is great!

And explained all steps to finally show how REST may help them if
they follow those patterns presented previously. So they will be
able to make the proper decision if they really need REST or not.
Great thing!

Amazing job!

Good new year to all of you!

Cheers,
Rodrigo.

Thanks guys :slight_smile: really great to hear this praise from you