October 20, 2016

A wild RESTful train appears!

If your rails framework is a subway system, then the rails generate scaffold command builds train tracks within your subway.

Imagine the vast labyrinth of an underground subway full of winding tracks going to different places. Your job as a developer is to be able to visualise what paths each train is supposed to take. Luckily you’re on the outside holding a map in your hands: you’ve got a top-down blueprint view of the subway system with all its various paths! But… as all the paths cross each other and there is no clear direction of where any of them are headed, you still have no idea which path even one train takes to make a full circuit.

You see, the train represents a transport that travels from one station to another; its intent doesn’t actually change - it’s a vehicle for messages. Whereas the passengers, that get on and off on the train, are the messages. Each message gets on and off at different stations - that is, at different points of the MVC architecture - with the aim of moving a payload of data across:

Subway  == Rails App          Station 1 == Router
Train   == Vehicle            Station 2 == Controller
People  == Messages           Station 3 == Model
Payload == Data               Station 4 == View

The Train enters the Subway through Station 1:
then    --> Station 2
then    --> Station 3*
back to --> Station 2 
then    --> Station 4

* where a secret (SQL) tunnel leads to a database

The following command should be familiar - it creates a scaffold for the Users resource with the name and email attributes:

rails generate scaffold Users name:string email:string

When this scaffold command is run, all four stations are set up for RESTful trains to access the ‘Users resource’. In fact, the subway is expecting 7 types of RESTful trains to run a ‘Users resource’ payload:

HTTP method	URL	Action	Purpose
GET	/users	index	get all users
GET	/users/:id	show	get user object labelled :id
GET	/users/new	new	get form for creating new user object
GET	/users/:id/edit	edit	get form for updating info on user object labelled :id
POST	/users	create	create a new user object; its :id is the next available row in your database
PUT	/users/:id	update	update a user object labelled :id with stuff
DELETE	/users/:id	destroy	destroy the user object labelled :id in the users database^[1]

The scaffold sets up a lot of tracks and stations for the train to use. This is achieved through a combination of placing new files in certain locations and placing written methods within those files. I use the verb ‘placing’ because under the hood, through much metaprogramming, Rails has already prescribed a lot of the code connecting and managing these pathways. As a developer, you get to do the fun part of plugging everything together.

A lot of ‘Users resource’ related files will populate the Rails app in order to achieve this setup. As a beginner you should sear the following project tree and flow diagram into your mind:

--app
  |--controllers
  |  |users_controller.rb     ------------- Station 2 ---------------
  |                               ▲          ▼     ▲         ▼
  |--models                       ▲          ▼     ▲         ▼
  |  |user.rb                     ▲         Station 3        ▼
  |                               ▲                          ▼
  |--views                        ▲                          ▼
     |--users                     ▲                    --------------
        |index.html.erb           ▲                                
        |show.html.erb            ▲                      Station 4  
        |new.html.erb             ▲                                
        |edit.html.erb            ▲                    --------------
--config                          ▲
  |routes.rb                  Station 1

*** A wild RESTful GET domain.com/users train appears! ***

All right, you are not going to fight this train and send it to a hospital like some crazy pokemon trainer, but you are certainly gonna track it. By tracking how the train moves from one location to another you will hopefully be able to see a pattern emerging for how the vehicle transfers messages for us:

The train enters the Subway (your Rails App).
The train heads for Station 1 (routes.rb) and drops off a GET /users HTTP request message.
The train receives a message called users#index and heads for Station 2 (users.controller.rb) expecting an index message.
On arrival to Station 2, the train receives the index message. The message reads out instructions on how to find the appropriate payload at Station 3. (user.rb)
Station 3 receives the train and returns the requested payload^[2] as documented in the index message.
The train loads the entire payload at Station 3 and then returns back towards Station 2.
When the train arrives at Station 2, the payload is packaged into more discrete containers so that it can be delivered to different sectors of Station 4 (index.html.erb).
Before leaving for Station 4, the train receives its last messages - these final messages allow Station 4 to unload the containers and plug in the data of the payload anywhere.
At Station 4, data from your payload is integrated into HTML and a webpage is constructed.
Finally, the train exits the subway and a webpage is delivered to the world.^[3] The train explodes into a million bits.

[2] Technically messages are passed to and fro between the model and the database through a secret (sql) tunnel in order to retrieve the correct payload. But for brevity and to minimise confusion, this has been ommitted.

[3] Some diagrams show the train reaching Station 4, picking up the webpage and then heading back to Station 2 before serving the webpage. Whatever the case may be, the important point is that you have understood how many stations the train has stopped at once it has entered the subway.

Now what happens when…

*** A wild RESTful GET domain.com/users/:id train appears *** ?