Configure an API Subdomain with Zero Downtime

What You Will Learn

• How to migrate an API subdomain between targets without downtime
• DNS TTL strategies for safe cutovers
• How to verify traffic flows before full migration
• Rollback procedures if something goes wrong
• How to monitor propagation across global resolver networks
• SSL certificate management during a DNS migration

Requirements

• An is-pro.dev subdomain currently pointing to an API endpoint
• Access to the is-cool-me dashboard at dash.is-pro.dev
• Ability to monitor API traffic (health check endpoint, logging, or metrics dashboard)
• dig or nslookup installed on your local machine
• Access to the new target platform to configure custom domain binding

Background Information

API subdomains like api.yourname.is-pro.dev serve production traffic. Changing DNS records carelessly causes 5XX errors for users, failed authentication flows, and integration timeouts for downstream services that depend on your API. The core challenge is that DNS resolution is cached aggressively at multiple layers — operating system resolvers, recursive resolvers (like those run by ISPs and Google Public DNS), and intermediate proxy caches. When you change a DNS record, it can take up to the old TTL value for every layer to pick up the change, during which traffic splinters between old and new targets.

The key to zero-downtime migration is reducing the TTL ahead of time so that changes propagate quickly once you make the switch, then using a careful cutover process that accounts for DNS caching, connection draining, and SSL certificate provisioning. This guide walks you through the precise sequence of steps to move your API subdomain from one target to another without any perceived downtime for your consumers.

The strategy applies whether your API subdomain uses an A record (pointing to an IP address), a CNAME record (pointing to another hostname), or an ALIAS/ANAME record at the apex. The same principles of pre-reduced TTL, staged cutover, and observability apply across all record types.

Step-by-Step Setup

Step 1: Lower TTL Before Migration

The single most important preparation step is reducing the TTL on your existing DNS record at least one full TTL period before you plan to make the change. This gives all caching resolvers worldwide time to pick up the shorter TTL, so that when you do switch the record value, the new value propagates in minutes instead of hours.

1. Log in to dash.is-pro.dev.
2. Select your subdomain and navigate to the DNS records section.
3. Find the record for your API subdomain (e.g. the api A or CNAME record).
4. Change the TTL field from its current value (commonly 3600, one hour) to 300 (five minutes).
5. Save the record and note the current time.

After reducing the TTL, you must wait for at least the duration of the old TTL before proceeding. If your old TTL was 3600 seconds (1 hour), wait at least one hour. This ensures that every resolver that had cached the old record value with the old (long) TTL has had a chance to re-query and learn the new (short) TTL. If you skip this wait, resolvers that still hold the old TTL will continue to cache the old value for the full original duration, negating the benefit of your TTL reduction.

Step 2: Prepare the New Target

While you wait for the TTL reduction to propagate, prepare the new API target. The goal is to have the new environment fully ready and verified so that the only remaining step when you cut over is a DNS change.

1. Deploy your API application to the new hosting provider or infrastructure.
   This could be a new cloud region, a different platform (e.g. migrating from a VPS to a serverless platform), or a different IP address within the same provider.
2. Verify the deployment works at its default URL.
   Every hosting platform assigns a temporary hostname — for example, my-app.onrender.com, my-app.vercel.app, my-app.fly.dev, or a direct IP address. Hit this URL with a browser or curl and confirm the API responds correctly.
3. Test every critical endpoint on the new target.
   Run your integration test suite against the temporary hostname. Pay special attention to:
   • Authentication flows (JWT issuance, OAuth callbacks, API key validation)
   • Database connectivity and data consistency
   • File upload and retrieval endpoints
   • WebSocket connections (if applicable)
   • Webhook delivery and callback URLs
   • Rate limiting and throttling behaviour
4. Configure custom domain binding on the new platform.
   Most hosting providers require you to add the custom domain (api.yourname.is-pro.dev) to their dashboard before they will accept traffic for it. This step typically involves adding a CNAME record or a verification TXT record — but on is-pro.dev, you already own the domain, so the new provider will ask you to verify ownership via a TXT record or by creating a CNAME. Complete this step so the provider's edge servers recognise the domain when traffic starts arriving.
5. Request or confirm SSL/TLS certificate issuance for the custom domain on the new provider.
   Platforms like Vercel, Netlify, Render, and Fly automate Let's Encrypt certificate provisioning. However, this can take 1–5 minutes and sometimes requires a manual retry. Ensure the certificate is active before the DNS cutover to avoid SSL errors for early adopters.

Step 3: Add the New Record

Once the TTL reduction has fully propagated and the new target is verified, you are ready to change the DNS record. This is the actual cutover moment.

1. Log in to dash.is-pro.dev.
2. Navigate to the DNS records section for your subdomain.
3. Edit the existing API subdomain record.
   Change the Value field to point to the new target. For a CNAME record, this will be the new provider's hostname (e.g. my-app.onrender.com). For an A record, this will be the new IP address.
4. Keep the Type the same as before. Changing the record type (e.g. from A to CNAME) can cause resolution failures during the propagation window because some resolvers may receive a different record type than they expect.
5. Keep the TTL at 300 (the reduced value from Step 1).
6. Save the record and immediately verify.

At this point, the DNS provider's authoritative layer is immediately serving the new record. However, recursive resolvers worldwide will only pick up the change as their cached entries expire — which, thanks to the pre-reduced TTL, will happen within 5 minutes for most users.

Step 4: Monitor During Propagation

The 30–60 minutes following the DNS change are the most critical. This is when traffic gradually shifts from the old target to the new target, and any misconfiguration will surface as increased error rates or latency.

• Watch your API monitoring dashboards — error rate, p50/p95/p99 latency, throughput, and 5XX responses. A spike in any of these metrics indicates a problem with the new target.
• Check both old and new endpoints resolve correctly by querying multiple public resolvers: dig @8.8.8.8 api.yourname.is-pro.dev, dig @1.1.1.1 api.yourname.is-pro.dev, and dig @208.67.222.222 api.yourname.is-pro.dev. This tells you how far DNS propagation has progressed across different resolver networks.
• Test the API from different geographic locations if you have access to a global observability tool (or friendly colleagues in other regions). Cloud providers often have regional load balancers or edge caches, and geography-based DNS behaviour can differ.
• Check SSL certificate validity using curl -vI https://api.yourname.is-pro.dev. A certificate mismatch or "SSL: no alternative certificate subject name matches" error means the new provider's certificate is not yet correctly configured.
• Verify that WebSocket connections (if used) upgrade properly: curl -H "Connection: Upgrade" -H "Upgrade: websocket" -H "Sec-WebSocket-Version: 13" -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" https://api.yourname.is-pro.dev and check for a 101 Switching Protocols response.

Step 5: Verify and Clean Up

Once monitoring confirms that all traffic is stable on the new target — typically after 24–48 hours of observing normal error rates and latency — you can clean up the old infrastructure.

1. Confirm all traffic is hitting the new target by checking the new provider's access logs or metrics dashboard for your custom domain. If you see zero requests for the old IP in your old provider's logs, the migration is complete.
2. Once stable, optionally increase TTL back to 3600 (or higher). A longer TTL reduces DNS query load on your DNS provider's authoritative infrastructure and improves client-side performance. There is no rush — you can keep TTL at 300 for days or weeks if you prefer.
3. Decommission the old target: shut down the old server, remove the old hosting configuration, and release any old IP addresses. Keep the old target's SSL certificate active for a few more days if possible, to serve any long-tail cached traffic.
4. Update your internal documentation, runbooks, and monitoring dashboards to reflect the new infrastructure.

Verification

Run the following commands to confirm the DNS migration is working correctly at every layer:

# Check the live record from your local resolver
dig api.yourname.is-pro.dev A +short
# Expected: the new target IP or CNAME

# Check propagation to Google Public DNS
dig @8.8.8.8 api.yourname.is-pro.dev A +short
# Expected: same as above

# Check propagation to Cloudflare DNS
dig @1.1.1.1 api.yourname.is-pro.dev A +short
# Expected: same as above

# Find the authoritative nameserver for the zone
dig NS is-pro.dev +short

# Check one authoritative nameserver directly (bypasses caches)
dig @<authoritative-ns> api.yourname.is-pro.dev A +short
# Expected: the new target value

# Verify the SSL certificate
curl -vI https://api.yourname.is-pro.dev 2>&1 | grep -i "SSL connection\|certificate\|subject"
# Expected: valid certificate, subject matches api.yourname.is-pro.dev

# Check that the API health endpoint responds correctly
curl -s -o /dev/null -w "%{http_code}" https://api.yourname.is-pro.dev/health
# Expected: 200

# Monitor for error rate spikes (run continuously during cutover)
watch -n 60 "curl -s -o /dev/null -w '%{http_code}' https://api.yourname.is-pro.dev/health"

If any of these return unexpected results (a different IP, an SSL error, or a non-200 status code), stop and diagnose before proceeding. Refer to the troubleshooting section below.

Troubleshooting

1. Partial propagation — some users still hitting the old target

Cause: DNS resolvers that cached the old value and old (long) TTL before you reduced the TTL will not re-query until their cache expires. This is the most common issue after a DNS change and is usually temporary.

Fix: Check an authoritative nameserver to confirm the new record is live: dig NS is-pro.dev +short then dig @<authoritative-ns> api.yourname.is-pro.dev A +short. If the authoritative server returns the new value, the record is correct. Wait for resolver caches to expire (up to the original TTL duration). You can also ask affected users to flush their local DNS cache. On Windows: ipconfig /flushdns. On macOS: sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder. On Linux: sudo systemd-resolve --flush-caches.

2. SSL certificate mismatch on the new target

Cause: The new hosting provider has not finished provisioning an SSL certificate for api.yourname.is-pro.dev. This is especially common with providers that issue certificates lazily when traffic first arrives, or that require manual domain verification via TXT records.

Fix: Log in to the new provider's dashboard and check the custom domain configuration. Look for a "Pending SSL" or "Certificate provisioning" status. Most providers have a "Retry" or "Renew" button. If the provider uses ACME-based certificate issuance (e.g. Let's Encrypt), ensure that the DNS record resolves correctly from the provider's perspective — some providers verify DNS from their own nameservers, which may not have picked up the change yet. Wait for propagation, then retry certificate issuance. As a workaround, you can temporarily route traffic through a reverse proxy that holds a valid certificate (like Cloudflare or a Caddy instance you control).

3. Rate limiting from the new provider

Cause: The new target (especially serverless or shared hosting platforms) may have rate limits that are lower than what your API traffic requires. When all traffic shifts over after DNS propagation, the sudden load can trigger rate limiting, causing 429 responses.

Fix: Check the new provider's documentation for concurrent request limits, bandwidth caps, and database connection limits. If possible, start with the DNS pointing to the new target during a low-traffic period and gradually shift traffic using a weighted record strategy (see FAQ). If the new provider supports auto-scaling, ensure it is configured to handle the expected peak load. Contact the provider's support to request a temporary limit increase during the migration window.

4. Mixed traffic hitting both old and new targets simultaneously

Cause: During the DNS propagation window, some resolvers return the old IP while others return the new IP. If your API maintains server-side state (e.g. in-memory session data, local file storage, or unshared caches), requests that land on the old target may behave differently than requests that land on the new target, leading to inconsistent user experiences.

Fix: The best mitigation is to architect your API as stateless from the start — store session data in a shared database or Redis instance that both targets can access. If that is not possible, implement a "sticky" cutover: keep both targets running, use a shared data store, and monitor until one target receives zero traffic before shutting it down. Another option is to use a reverse proxy in front of both targets that can drain connections gracefully.

5. Rollback procedure — reverting to the old target

If monitoring reveals a critical issue with the new target after the DNS change, you may need to roll back. Because you kept the old target running, rollback is straightforward:

1. Edit the API subdomain record in the is-cool-me dashboard.
2. Change the Value back to the old target (the original IP or CNAME).
3. Save the record. Because the TTL is still at 300, the rollback propagates as quickly as the original change — within 5 minutes for most users.
4. Verify that traffic is now hitting the old target by checking the old provider's metrics and access logs.
5. Investigate the root cause of the failure on the new target before attempting the migration again.

DNS Propagation Notes Specific to API Migrations

API migrations have distinct characteristics that affect DNS propagation behaviour:

• High request volume. APIs often receive thousands of requests per minute from a relatively small number of clients (mobile apps, SPAs, server-to-server integrations). These clients typically have aggressive DNS caching, so a pre-reduced TTL is essential — many mobile app DNS libraries respect the TTL from the resolver, but some hard-code a minimum cache duration of 60 seconds regardless of TTL.
• Persistent connections. Many API clients use HTTP keep-alive or connection pooling, which means they resolve DNS once and reuse the connection for many requests. Changing DNS alone does not force these clients to reconnect to the new target. You may need to coordinate the cutover with the client team, or gracefully terminate old connections at the infrastructure level.
• API gateways and reverse proxies. If you have an API gateway (Kong, Tyk, AWS API Gateway) or reverse proxy (Nginx, Envoy) in front of your backend, the DNS change may need to be made at the gateway level rather than at the is-pro.dev DNS level. In this architecture, the gateway resolves the backend hostname internally, so you would change the backend DNS (or the gateway's upstream configuration) rather than the public-facing DNS.
• Health check endpoints. Use a dedicated health check endpoint (/health or /status) that is fast, does not require authentication, and returns immediately. Load balancers, orchestration systems, and monitoring tools rely on this endpoint to determine target health. Ensure the new target's health check returns 200 before you cut over DNS.

Best Practices

• Cut over during low-traffic periods. Schedule your DNS change for a time when API traffic is at its daily minimum. For consumer-facing APIs, this is typically 2:00–5:00 AM local time. Check your traffic graphs to identify the lowest-usage window.
• Always have a rollback plan. Before making the DNS change, write down the exact steps to revert. Keep the old TTL value noted so you know what to restore it to. Document the rollback procedure in a runbook that a teammate could follow without your input.
• Test production endpoints before switching. Use the new provider's temporary URL to run your full test suite, including integration tests that exercise database writes, external API calls, and webhook deliveries. A staging environment that mirrors production is ideal, but testing against the actual production deployment (with a staging database) is a close second.
• Monitor error rates for 24 hours post-migration. Some issues surface only after users have been interacting with the new target for several hours — for example, memory leaks, connection pool exhaustion, or timezone-dependent bugs. Keep your monitoring dashboards visible and set up alerts for any error rate increase above baseline.
• Communicate the migration to API consumers. If your API is consumed by external teams or third-party applications, notify them in advance of the migration window. Provide the new target's temporary URL so they can test their integration ahead of time. After the migration, confirm that all integrations are working.
• Keep both old and new logging active. During the propagation window, collect logs from both targets. If a request fails on the new target, you can cross-reference the old target's logs to determine whether the request was handled correctly before the change.
• Use infrastructure as code for your DNS configuration. If you manage your DNS records through Terraform, Pulumi, or a similar tool, the migration becomes a simple diff-and-apply workflow. IaC also makes it easier to revert to the previous state if needed.

FAQ

Can I use weighted DNS records for a gradual cutover?

Weighted records (sometimes called traffic steering or split horizon DNS) allow you to send a percentage of queries to one target and the remainder to another. This is useful for gradual rollouts. On is-pro.dev, weighted records are not natively supported in the dashboard, but you can achieve a similar effect by running your own authoritative DNS infrastructure or by using a DNS load-balancing service in front of is-pro.dev. For most users, the simpler approach of pre-reduced TTL followed by a single cutover is sufficient and less error-prone.

What if my API uses WebSockets?

WebSocket connections are typically long-lived and use HTTP/1.1 upgrade semantics. After a DNS change, existing WebSocket connections continue to hit the old target until the client disconnects and reconnects. To minimise disruption, configure your old target to send a "graceful shutdown" signal (e.g. a close frame with a reconnect hint) during the migration window. On the new target, ensure WebSocket handshake and upgrade work correctly by testing with tools like websocat or a custom WebSocket client before the DNS cutover.

How do I handle SSL during migration?

SSL is often the trickiest part of a DNS migration because certificate issuance and DNS propagation are interdependent. The ideal sequence is: (1) configure the custom domain on the new provider, (2) verify DNS at the provider level (they may test from their own DNS infra), (3) trigger certificate issuance, (4) confirm the certificate is active, and (5) cut over DNS. If the provider requires the DNS record to point to them before issuing a certificate, you have a chicken-and-egg problem — in that case, accept a brief SSL gap during cutover, or use a shared reverse proxy that holds a wildcard certificate for both targets.

What happens to cached DNS in mobile apps?

Mobile operating systems and apps often implement custom DNS caching that does not strictly follow TTL values. iOS, for example, caches DNS results for up to 10–15 minutes even when the TTL is lower. Android's DNS behaviour varies by manufacturer and OS version. This means that even with a TTL of 60 seconds, some mobile users may continue hitting the old target for up to 15 minutes after the change. This is normal — just ensure both targets remain operational during this window.

Do I need to worry about DNSSEC during migration?

If your subdomain is DNSSEC-signed, changing the DNS record while the DNSSEC signatures remain valid should work transparently — the signatures cover the record set, not the specific value. However, if you change the record type (e.g. from A to CNAME), the DNSSEC chain of trust may break for resolvers that validated the old record type. The safest approach is to change only the value, not the type, and to avoid modifying DNSSEC signing parameters during the migration window.

How do I migrate an apex domain (yourname.is-pro.dev) that serves an API?

The apex (bare domain) cannot use a CNAME record. If your API is served from the apex, you must use an A or AAAA record (pointing to an IP address) or an ALIAS/ANAME record if your DNS provider supports it (is-pro.dev does support synthetic ANAME records at the apex). The migration steps are the same, but instead of editing a CNAME value, you change the A record to the new IP. Note that some hosting providers do not support apex custom domains for this reason — check with your new provider before migrating.

Can I automate the entire migration with CI/CD?

Yes. You can automate most or all of this workflow through your DNS provider's API or IaC tooling (such as Terraform) if your environment exposes those capabilities. For example, you could have a CI/CD job that: (1) deploys the API to the new target, (2) runs integration tests against the temporary URL, (3) updates the DNS record via an automated apply step, (4) runs post-migration smoke tests, and (5) monitors for a configurable cooldown period before declaring success.

Related Guides

• Create Wildcard Records Safely
• Diagnose SSL Pending on a New Subdomain
• Migrate a Subdomain Between Hosting Providers
• Build a DNS Change Checklist for Teams

For a deeper look at DNS propagation mechanics, read our blog post DNS Propagation Explained.

Conclusion

Migrating an API subdomain to a new target without downtime comes down to three principles: prepare ahead of time, reduce your TTL before making the change, and keep both targets running until you are certain the migration is complete. The pre-reduced TTL is the single most important step — without it, your DNS change can take hours to propagate, leaving users stranded on a stale endpoint that you may have already decomissioned.

By following the step-by-step workflow in this guide — pre-reduce TTL, prepare and verify the new target, update the DNS record, monitor propagation, and clean up only after stability is confirmed — you can move your API subdomain between hosting providers, cloud regions, or IP addresses with zero perceived downtime for your consumers.

Remember to always have a rollback plan, communicate with your API consumers about the migration window, and keep your observability tooling active for at least 24 hours after the cutover. The is-pro.dev Discord community is a great place to ask questions if you run into issues during your migration.

Deployment scenario from operations

An API migration required zero downtime while clients with aggressive DNS caching continued hitting old endpoints.

Common mistakes

• Migrating API DNS without checking client cache behavior and retry logic.
• Changing origin and certificates at the same time without staged checks.
• Not validating health endpoints before and after cutover.

How to verify it works

1. Probe API health and key endpoints before and after DNS swap.
2. Monitor error rate and latency during TTL transition windows.
3. Confirm TLS and host routing for API clients from at least two networks.