How to select a future-proof subdomain structure for your SaaS web app

So you’ve finally decided on the name for your new SaaS app and bought a domain name. Exciting times!

One of your first technical decisions will be to select subdomains for where its web properties will be hosted. You don’t want to prematurely optimise, but by selecting a sensible set of subdomains for your different web properties at this stage, you will help prevent these headaches down the road:

• Marketing folks breaking the routing in your app
• Developers breaking the styles of the marketing site
• Managing complex redirect configurations
• A need for reverse proxies in your app architecture
• SEO penalties

Keep your web app separate from the marketing site

If you’re a one-person team who will be building both the web app and writing the marketing content, you may be tempted to keep both under the same subdomain. After all, you would be able to share resources such as CSS and logos between sites and save on having to pay for separate hosting.

However, you may in the future hire non-technical marketing staff who will need to add new or amend existing content. To make it easy for them to work independently, you may wish to use a CMS (e.g. Wordpress). This would typically need to be running on their own server and probably wouldn’t be the same server-side technologies you are using to build your web app (e.g. Ruby/Rails, Nodejs/Express, Python/Django). You also don’t want to worry about causing downtime to the marketing site if you’re performing maintenance on the app, or about breaking CSS styles on the marketing site when you change a rule in the app.

Using the same subdomain also rules out the option of using a static CDN-hosted marketing website to improve load-time performance and reduce hosting costs.

Selecting a subdomain name for your app

The simplest option is just to use app as it’s not too specific as to the purpose so you keep your options open should the scope of the web app increase over time. This is familiar to B2B and B2C users and is used by popular services such as YNAB, Sendgrid and Optimizely. It also has the advantage of being short, making URLs easier to read in your user’s browser.

Other common options are:

Prefer the naked domain over “www” for your marketing site

This is more subjective than my other recommendations and there are arguments for and against both of these options, from UX and technical configuration perspectives. My reasoning for choosing the naked domain (sometimes referred to as the apex or bare domain) over “www” is because the latter is superfluous to most web users today and it the naked domain is pretty easy to configure in AWS Route 53 and CloudFront (my DNS and static website hosts of choice).

Whichever option you go for, make sure to configure your site to redirect one to the other.

Keep your marketing site and blog on the same subdomain

I would recommend hosting your blog as part of the same site as your marketing site, under a subfolder such as mydomain.com/blog/. Marketing folks tend to be the people updating the marketing site and the blog. By using the same CMS hosted under the same site, it will be easier for them to make their changes. A single site also allows branding and site layout (common header, nav and footer) to be applied in one place. Additionally, analytics are simplified as only one web property needs to be configured in Google Analytics and Google Search Console. Finally, it seems to now be SEO best practice to “Favor subfolders/subdirectories over subdomains”.

Keep your API on the same subdomain as your app (for now)

This decision only really matters whenever you are making your API publicly available. I would contend that you shouldn’t be making any API publicly available as part of v1 of your app, as external inbound integrations are rarely a core must-have feature for your users. At this stage, your API should be private and only consumed by AJAX calls from your web app. For that reason, unless the API is the absolute core of your app (as opposed to just a means to integrate with it), I would recommend keeping it under the same subdomain as your main portal app for your first release.

If and when you do decide to make your API publicly available, consider hosting it under it’s own api subdomain. How you architect your app’s code (i.e. in modules within a single monolith app, or in a separate repository under a microservice-style architecture) is largely beyond the scope of this article. However, if you do have separate microservices for your web app and your API, then you would need to introduce a reverse proxy (e.g. Nginx) into your architecture to perform path-based routing of a request to the correct service handler. On the other hand, if you have separate subdomains, this routing is handled at the DNS level which is much simpler.

Use one SSL certificate for all your properties

If you want to make some or all your web properties accessible over HTTPS, you can do so using a single SSL certificate with the following 2 Subject Alternative Names configured:

mydomain.com
*.mydomain.com

You do not need to explicitly specify individual subdomains as they’re all covered by the wildcard *. However, the naked domain isn’t covered by the wildcard, so it needs to be listed as a separate item.

TL;DR

Stick to the following recommendations and you won’t go far wrong:

• Use your naked domain (mydomain.com) for the marketing site
• Host your blog as part of the marketing site under the mydomain.com/blog/ or mydomain.com/articles/ folder path
• Use app.mydomain.com as the subdomain for the web app
• Host your private API at app.mydomain.com/api/v1/
• Host your public API at api.mydomain.com/v1/ (but don’t do this until it’s needed)
• Use HTTPS for all properties

Originally published at winterwindsoftware.com