Route structure for support.theguardian.com

[jamesgorrie]

The route structure support.theguardian.com has some structure, but seems seems missing in some areas. The challenges and potential fixes to those are discussed below.

Where we are now

Challenges and outcomes to address them

Based on some of the challenges we have had, a good outcome from this URL design would:

• Make it easy to add things without having to think about where they should go. Digital subscriptions and the new three tier are current examples
• Allow the product team to easily guess what a URL is and what it's referencing
• Make it easy to communicate externally
• Help inform the organisation of our slightly fragmented controller / UI structure
• Removal of unused URLs that add to tech debt and cognitive load
• Help us migrate to a more universal checkout process (use the S+ checkout for other subscriptions)
• ...

This is part of the larger domain design project.

This is not to disallow product and other stakeholders having vanity URLs that are easy to remember and share that redirect.

Current state

URL	Controller	UI	Aliases / examples
/{geo}/contribute	Application.contributionsLanding	supporter-plus-landing	/support, /showcase
/{geo}/subscribe/{product}{?/step}	SubscriptionsController	subscriptions-landing
/{geo}/subscribe/digital	DigitalSubscriptionController	digital-subscriber-checkout
Payment / worker APIs	Various	N/A	/contribute/recurring/create, /support-workers/status
Payment services	StripeController, PaypalController	N/A	/stripe/create-setup-intent/recaptcha, /stripe/create-setup-intent/prb
Guardian services	IdentityController, PricesController	N/A	/contribute/send-marketing, /identity/get-user-type, /identity/signin-url, /prices
Utilities	Various	Various	/aus-2020-map, /aus-map, /thank-you-shareable-articles

This isn't exhaustive, you can see a more full view of our routes here.

Potential future

The most impactful feels like it would be around the public URLs with UIs to them as this is where a lot of the product work, thus cognitive load, is.

Standardise around our product offering

Currently there is the most structure around our subscriptions. The outlier from a route perspective is /{geo}/contribute.

From a UI perspective /{geo}/subscribe/digital is an outlier as it uses a similar controller to /contribute.

The current /{geo}/subscribe/{product}/{?/step} seems to be a good fit. Most of our products are subscriptions.

This is also common language used across the publishing and news domain.

e.g.

/{geo}/subscribe           SubscriptionsController.index()
/{geo}/subscribe/plus      SubscriptionsController.plus()
/{geo}/subscribe/digital   SubscriptionsController.digital()
/{geo}/subscribe/paper     SubscriptionsController.paper()
/{geo}/subscribe/weekly    SubscriptionsController.weekly()
# Is this potentially controversial due to it not technically being a subscription?
/{geo}/subscribe/recurring  SubscriptionsController.recurring()
/{geo}/subscribe/one-time  SubscriptionsController.oneTime()

Considerations

• Would changing /{geo}/contribute => /{geo}/subscribe have SEO implications
• Does this scale to when we want to add non-subscription products? Not sure we have examples here besides On-time donations
• What do we do about landing pages such as the three-tier test. This might also contain the current /contribute route as it's actually a few products, one-time, recurring and plus.

Alternatives

Continue as is?

Pros:

• No extra work

Cons:

• Harder for new people joining to get up to speed

Move to a whole new model e.g. Products model

e.g.

/{geo}/products                     ProductsController.index()
/{geo}/products/subscribe           SubscriptionsController.index()
/{geo}/products/subscribe/plus      SubscriptionsController.plus()
/{geo}/products/subscribe/digital   SubscriptionsController.digital()
/{geo}/products/subscribe/paper     SubscriptionsController.paper()
/{geo}/products/subscribe/weekly    SubscriptionsController.weekly()
/{geo}/products/donate              ProductsController.donate()

Pros:

• adds another level of categorisation which could scale out to non-subscription based products

Cons:

• Significantly larger refactor without having many examples

---

These are some other thoughts, but could be worth scoping them separately:

Differentiate between API style domains and UI domains

Currently API style endpoints all live on the root, we could move these out to live under /apis to make it clear that these are accessed via the client.

This should be a no-op from an SEO / user perspective as no-one references these routes bar us.