Technical Story: PT1-148

Context and Problem Statement¶

With the growing number of client-side routes, the naming of the routes is becoming harder and unpredictable. We need a clear naming guideline for the routes so that we can be consistent and easily predict what the next route should be called.

Decision Drivers¶

• Routes should be following a clear pattern
• Routes should be easy to name when adding new pages
• Route names should be easily predictable

Considered Options¶

• Verb routes
• Rest routes
• Hybrid (rest and verbs)

Decision Outcome¶

Chosen option: [Hybrid (rest and verbs)], because it brings the best of both worlds, it has good base rules like REST and it brings that extra clarify which verbs provide

Positive Consequences ¶

• Clear guideline of naming routes
• Consistency of routes
• Predictable routes

Negative Consequences ¶

• A bit limited on the various scenarios that might need to be depicted
• Can get a bit long when resources are nested

Pros and Cons of the Options¶

Verb-like routes¶

• Good, because its easier to capture the exact role of the route/page
• Good, because it can result in shorter urls due to the naming freedom
• Bad, because route names are somewhat unpredictable and ambiguous
• Bad, because its hard to define a naming guideline

Rest-like routes¶

• Good, because it uses a familiar concept with clear rules
• Good, because route names are predictable
• Bad, because with the lack of context that HTTP verbs bring, we cannot efficiently represent all routes
• Bad, because it lacks a bit of freedom to capture the essence of some route
• Bad, because routes can get a bit long in some cases due to the nature of the resources

Hybrid (rest and verbs)¶

• Good, because it has a good base of rules to help us stay on the right naming track
• Good, because it uses finite set of verbs, which does not allow us to go off track with the verbs
• Good, because they are easily predictable and easy to come up with naming for new routes
• Bad, because they can get a bit long if we have many nested resources

Guide on naming routes¶

• We use route suffix (/new and /edit) to make up for the context which HTTP verbs usually bring in REST
• We always use plural form of resources/subresources/
• We always use lowercase letters separated by dash

Examples of resources(itineraries) and subresources(accommodations):¶

• To view all itineraries: /itineraries
• To create new itinerary: /itineraries/new
• To view single resource: /itineraries/:id

• To update a resource: /itineraries/:id/edit

• To view all accommodations which are part of itinerary: /itineraries/:id:/accommodations
• To create new accommodation which will belong to itinerary: /itineraries/:id/accommodations/new
• To view single accommodation which belongs to itinerary: /itineraries/:id/accommodations/:accId
• To update an accommodation which belongs to itinerary: /itineraries/:id/accommodations/:accId/edit

Links¶

• Inspired by REST resource naming guidelines
• Inspired by Ruby on Rails routing