Migration Guide: v1/v2 to v3

This guide will help you migrate from API v1 or v2 to API v3. The migration is straightforward - the main change is adding an API key header to your requests.

Overview

API v3 maintains the same endpoint structure and response format as v1 and v2. The only difference is the requirement for an API key in the request headers.

Step 1: Get an API Key

Before migrating, you'll need an API key. See our Getting an API Key guide for instructions.

Step 2: Update Your Endpoints

Change the version in your API URLs from v1 or v2 to v3:

Before (v1/v2):

https://www.aptosnames.com/api/mainnet/v1/address/test
https://www.aptosnames.com/api/mainnet/v2/address/test

After (v3):

https://www.aptosnames.com/api/mainnet/v3/address/test

Step 3: Add API Key Header

Add the X-API-Key header to all your requests:

Using cURL

Before:

curl https://www.aptosnames.com/api/mainnet/v1/address/test

After:

curl -H "X-API-Key: YOUR_API_KEY" \
  https://www.aptosnames.com/api/mainnet/v3/address/test

Using JavaScript/TypeScript

Before:

export async function getAddressFromNameBefore(name: string) {
  const response = await fetch(`https://www.aptosnames.com/api/mainnet/v1/address/${name}`);

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  const { address } = await response.json();
  return address;
}

After:

export async function getAddressFromNameAfter(name: string) {
  const API_KEY = process.env.APTOS_NAMES_API_KEY;

  if (!API_KEY) {
    throw new Error("APTOS_NAMES_API_KEY environment variable is required");
  }

  const response = await fetch(`https://www.aptosnames.com/api/mainnet/v3/address/${name}`, {
    headers: {
      "X-API-Key": API_KEY,
    },
  });

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  const { address } = await response.json();
  return address;
}

Using Python

Before:

import requests

response = requests.get(
    "https://www.aptosnames.com/api/mainnet/v1/address/test"
)

After:

import requests

headers = {
    "X-API-Key": "YOUR_API_KEY"
}

response = requests.get(
    "https://www.aptosnames.com/api/mainnet/v3/address/test",
    headers=headers
)

Endpoint Mapping

All endpoints are available in v3 with the same paths:

Response Format

Response formats remain unchanged. All endpoints return the same JSON structure as v1 and v2.

Error Handling

Missing API Key

If you don't include an API key, you'll receive a 401 Unauthorized response:

{
  "error": "API key required. See documentation for details."
}

Invalid API Key

If you provide an invalid API key, you'll receive a 401 Unauthorized response:

{
  "error": "Invalid API key"
}

Complete Example

Here's a complete example showing the migration:

Before (v1/v2)

export async function getAddressFromNameBefore(name: string) {
  const response = await fetch(`https://www.aptosnames.com/api/mainnet/v1/address/${name}`);

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  const { address } = await response.json();
  return address;
}

After (v3)

export async function getAddressFromNameAfter(name: string) {
  const API_KEY = process.env.APTOS_NAMES_API_KEY;

  if (!API_KEY) {
    throw new Error("APTOS_NAMES_API_KEY environment variable is required");
  }

  const response = await fetch(`https://www.aptosnames.com/api/mainnet/v3/address/${name}`, {
    headers: {
      "X-API-Key": API_KEY,
    },
  });

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  const { address } = await response.json();
  return address;
}

Environment Variables

We recommend storing your API key in an environment variable:

# .env
APTOS_NAMES_API_KEY=your_api_key_here

Then use it in your code:

export function getApiKeyFromEnv() {
  const API_KEY = process.env.APTOS_NAMES_API_KEY;

  if (!API_KEY) {
    throw new Error("APTOS_NAMES_API_KEY environment variable is required");
  }

  return API_KEY;
}

Testing Your Migration

1. Update one endpoint at a time
2. Test with your API key
3. Verify responses match expected format
4. Update error handling if needed
5. Deploy and monitor