Custom Domains Redesign: New API Available

Developers
,
1

Hello everyone,

We are excited to announce the redesign of the popular Custom Domains service! This update brings a more robust, reliable, and simplified experience for managing your custom domains for canisters hosted on the Internet Computer.

What’s New

The new service uses a cleaner, more intuitive API design:

  • Domain name as identifier: No more registration IDs. The domain name itself is now the ID.

  • RESTful endpoints: All operations use standard HTTP methods with the domain name in the path:

    • POST /custom-domains/v1/{domain} - Register a domain

    • GET /custom-domains/v1/{domain} - Check registration status

    • PATCH /custom-domains/v1/{domain} - Update domain mapping

    • DELETE /custom-domains/v1/{domain} - Remove a domain

    • GET /custom-domains/v1/{domain}/validate - Validate DNS configuration before registering

  • Clear JSON responses: All responses follow a consistent structure with clear status indicators, helpful messages, and detailed error information.

Migration Timeline

For new registrations: Please use the new service starting now. The new API is available and ready for production use. The docs are available on internetcomputer.org.

For existing domains: No action required on your part! We will automatically migrate all existing custom domains to the new service over the coming weeks.

Here is our migration plan:

1. Phase 1 (Now): Both services run in parallel. New registrations should use the new service.

2. Phase 2 (Coming weeks): We will disable new registrations on the old service and migrate the domains to the new service.

3. Phase 3 (After migration): Once all existing domains are migrated, we will shut down the old service and maintain only the new one.

Getting Started

For detailed instructions on using the new service, including DNS configuration, registration steps, and troubleshooting, please refer to our updated documentation.

Questions?

If you have any questions or encounter issues, please check the documentation or reach out in this thread. We’re here to help!

Note: The old service will continue to work for existing domains during the migration period. We will provide updates as we progress through each phase of the migration.

11 Likes
2

this is great @rbirkner! thanks!

3

Implementing the new API was a breeze and the results are awesome! It feels much faster, and adding the /validate step in the UI wizard added a nice bit of flair. Great work team! :flexed_biceps:

2 Likes
4

Hello everyone,

We are starting with Phase 2 this week. In the next couple of days, we will disable all registrations and mutations of the custom domains in the old custom domain service. When you try to use that, you will get an error with a short description:

This endpoint is deprecated, please use the new Custom Domains API.
See the documentation here: https://internetcomputer.org/docs/building-apps/frontends/custom-domains/using-custom-domains

Important: Existing custom domains continue to work. If you want to add a new domain, please use the new service.

We will start the migration of all the custom domains from the old to the new service shortly after. It will take roughly two weeks to space the registrations out evenly.

Thanks a lot for your understanding!

5 Likes