v4 To Core API Migration Guide
Last updated

v4 To Core API Migration Guide

Why Upgrade?

  • OpenAPI 3.1-based documentation for better tooling and interactive exploration.
  • Cleaner, consistent error messages and HTTP status codes.
  • Streamlined, consolidated endpoints (e.g. UpdateDomain).
  • Enforced standards for content types and default response formatting

Upgrading from Legacy v4 API to Core API v1.0

Welcome to the Name.com Core API v1.0! This new API offers a modern, RESTful interface for managing your domains, DNS records, and related services, succeeding our legacy v4 API. We've rebuilt the Core API from the ground up to provide faster iteration, improved stability, more consistent behavior, and a better overall developer experience.

IMPORTANT: Breaking Changes

Migrating from the v4 API to the Core API v1.0 is a breaking change. You will need to review and update your existing integrations to align with the new API structure, endpoints, and behaviors outlined below. The v4 API remains accessible for a transition period, but we strongly encourage all new integrations and existing integrations to migrate to the Core API v1.0.

Key Changes Requiring Your Attention & Migration Steps:

  1. New API Documentation (OpenAPI 3.1)
    • What changed: The Core API documentation is now provided in OpenAPI 3.1 format.
    • Why: This offers significantly better tooling support, interactive documentation capabilities (e.g., "Try it out" features), and clearer schema definitions.
    • Action Required: Familiarize yourself with the new documentation structure. You can leverage a wide range of OpenAPI 3.1 compatible tools to generate client libraries, explore endpoints, and understand request/response models.
  2. Improved Error Handling & Messaging
    • What changed: We've overhauled error responses for clarity and accuracy.
      • Generic 500 Internal Server Error responses for many client-side or predictable error conditions have been replaced with more specific and appropriate HTTP status codes.
      • Authentication errors, previously sometimes indicated by a 403 Forbidden response, will now consistently return a 401 Unauthorized response. The 403 Forbidden status is now exclusively used when an authenticated user attempts an action they are not permitted to perform.
    • Example (Error Code): If an action fails due to insufficient account credit, the API will now return 402 Payment Required instead of the previous 500 Internal Server Error.
    • Action Required:
      • Review your error handling logic. Update it to expect and correctly process more specific HTTP status codes (e.g., 4xx client error codes like 401, 402, 422) instead of relying on generic 500 errors for actionable issues.
      • Adjust authentication failure checks to look for 401 Unauthorized. Treat 403 Forbidden as a permissions issue for an authenticated user.
  3. Consistent Default Values in API Responses
    • What changed: API responses will now consistently include fields with their default values (e.g., false for booleans, 0 for numbers, "" for empty strings) instead of omitting them.
    • Example: The Search API previously omitted "purchasable": false; it is now explicitly returned as "purchasable": false.
    • Action Required: Update your response parsing logic to expect these default values. You should no longer assume that an omitted field implies a specific default (like false or null). This change can make your client-side data handling more explicit.
  4. Correct Content-Type Headers in API Responses
    • What changed: The API will now accurately set the Content-Type header based on the response data. For JSON responses, this will be Content-Type: application/json.
    • Previously: Content-Type: text/html was often incorrectly returned for JSON responses.
    • Action Required: Ensure your client correctly interprets the Content-Type: application/json header for JSON responses. If your client was previously ignoring or misinterpreting this header, updates may be needed.
  5. Enforced Content-Type Header Requirements for Requests
    • What changed: The Content-Type: application/json header is now strictly enforced for all PUT, POST, and PATCH requests.
    • Previously: While documented as required, this was not consistently enforced.
    • Behavior: If this header is missing, or contains a value other than application/json, the API will return a 415 Unsupported Media Type error.
    • Important Note for Body-less POSTs: Due to server implementations, this enforcement means that even POST requests that do not require an actual request body (e.g., certain RPC-style actions like the now-deprecated LockDomain) will still require the Content-Type: application/json header.
    • Action Required:
      • For all PUT, POST, and PATCH requests made to the Core API v1.0, you must include the header: Content-Type: application/json.
      • Verify this for requests that previously worked without it, including those that don't send a JSON body.
  6. Consolidated Domain Update Functionality & Endpoint Deprecations
    • What changed: Several individual API endpoints for modifying domain settings have been deprecated. A new, consolidated endpoint, UpdateDomain, has been introduced to handle these actions.
    • Deprecated Endpoints:
    • New Endpoint: PATCH /v1/domains/{domainName} (See DomainUpdate Documentation)
    • Action Required:
      • Migrate your domain modification logic from the deprecated endpoints to the new UpdateDomain endpoint. This endpoint allows for updating domain lock status, autorenew settings, and WHOIS Privacy settings in a single call.
      • While the deprecated v4 endpoints remain accessible for now, they will be removed in a future API version. Prioritize this migration.

Removed Features

  • SearchStream Endpoint:
    • This endpoint has been removed in Core API v1.0. We are evaluating a revised implementation for a future release.
    • Action Required: If your application uses the SearchStream endpoint, you will need to remove this integration.

New Features

  • UpdateDomain Endpoint:
    • A new endpoint (PATCH /v1/domains/{domainName}) provides a consolidated and more efficient way to modify multiple domain settings such as autorenew status, WHOIS Privacy, and domain lock status.
    • Recommendation: Utilize this new endpoint for all domain setting modifications. Refer to the DomainUpdate Documentation for details.

Overall Benefits & Next Steps

The Core API v1.0 is designed for improved usability, consistency, and future extensibility. The underlying codebase rewrite allows us to iterate faster, provide better error handling, and ensure more consistent behavior across all endpoints. We encourage you to:

  1. Thoroughly review this guide and the new Core API v1.0 documentation.
  2. Plan your migration from the v4 API, prioritizing the changes outlined above.
  3. Test your updated integration extensively in a development or staging environment if available.

While the legacy v4 API remains accessible during a transition period, all new development should use the Core API v1.0.

We appreciate your partnership and are excited to provide you with a more robust and modern API experience. Please refer to our official documentation for complete details and contact our support channels if you have any questions during your upgrade process.

Previous page
Next page