REST-based routing

rest_based_routing.txt

The idea is to have the notion of a 'resource' that is being edited. This isn't a hard rule,
but generally most edit patterns follow this structure. Anything custom can be easily made
to be different.

Let's say I have the notion of a 'prospect' in the system that I can modify. The number of
attributes it has are unimportant at the moment, it's more about the high-level logical
resource that is being modified. Using REST-based resource routing, most frameworks
would give you something like this (this is Rails-based, but others are similar):

  endpoint        | verb   | controller file              | action (function to be executed)
------------------|--------|------------------------------|--------------------------------- 
/prospects        | POST   | prospects_controller.php     | create (with form parameters given)
/prospects/1      | GET    | prospects_controller.php     | show (the singular instance id 1, this is also 'read')
/prospects/1      | PUT    | prospects_controller.php     | update (with form parameters given for id 1)
/prospects/1      | DELETE | prospects_controller.php     | delete (id 1)
/prospects/1/edit | GET    | prospects_controller.php     | edit (renders form with all current attributes)
/prospects        | GET    | prospects_controller.php     | index (renders all instances in a table, etc.)
/prospects/new    | GET    | prospects_controller.php     | new (renders empty form))

If you had another resource, say 'url', you'd have more entries:
/urls             | POST   | urls_controller.php          | create (with form parameters given)
/urls/5           | GET    | urls_controller.php          | show (the singular instance id 5)
...

In addition to executing the appropriate function in the right class, the framework will also
give you a 'parameters' object containing everything you need to know about what was given in the
request, including the 'id' that came from the url. This makes it really easy to look up
resources from a database (or wherever else) before doing any data mutation. Code becomes
pretty clean.

There is also the notion of a 'singular' resource, effectively where you only have one in the system.
A common example of this is a user profile. While there may be many in the system, the user may
only ever see one which is their own. The routes change slightly:
/profile          | POST   | profiles_controller.php      | create (with form parameters given)
/profile          | GET    | profiles_controller.php      | show (Note this used to be 'index' for plural routes)
/profile          | PUT    | profiles_controller.php      | update (with form parameters given)
/profile          | DELETE | profiles_controller.php      | delete (the only one that exists, the current user's, tends to be a 'reset')
/profile/edit     | GET    | profiles_controller.php      | edit (renders form with all current attributes)

The routers in most frameworks end up determining which method in which controller to run based
on the incoming request. This is largely to make your life easier as a programmer to have a pattern
to know where to look for the code that runs on a particular request. And the *key* aspect
to this whole thing is that you can now read a URL combined with the HTTP verb and know exactly
the intent behind the action.

The previous world used to be SOAP-based APIs where you had one endpoint and the code determined
what to do based on the payload data. This worked, but you did not know what was going to happen
by simply looking at the URL and verb. This is the main benefit to REST-based routing is you
can just see what it's supposed to do.