logo
Getting started

Manage DNS Records

Full flow for registering with records, reading existing records, and updating DNS

This guide covers the full DNS flow:

  1. Register a domain with initial records.
  2. Fetch the current zone records.
  3. Update existing records in batch.
  4. Create any missing records.
  5. Create any missing records.
  6. Verify final state.

End-to-end example

import { createNamefiClient } from '@namefi/api-client';
import { setTimeout as sleep } from 'node:timers/promises';

const client = createNamefiClient({
  authentication: {
    apiKey: process.env.NAMEFI_API_KEY!,
    type: 'API_KEY',
  },
  logger: true,
});

const zoneName = 'example.com';

// 1) Register domain and seed initial DNS records
const order = await client.orders.registerWithRecords({
  normalizedDomainName: zoneName,
  durationInYears: 1,
  records: [
    { name: '@', type: 'A', rdata: '203.0.113.10', ttl: 300 },
    { name: 'www', type: 'CNAME', rdata: 'example.com.', ttl: 300 },
  ],
});

// 2) Wait for order processing to finish
const terminalStatuses = new Set([
  'SUCCEEDED',
  'FAILED',
  'CANCELLED',
  'PARTIALLY_COMPLETED',
]);

while (true) {
  const current = await client.orders.getOrder({ orderId: order.id });
  if (terminalStatuses.has(current.order.status)) {
    console.log('Final order status:', current.order.status);
    break;
  }
  await sleep(5_000);
}

// 3) Check existing records
const existing = await client.dnsRecords.getRecords({ zoneName });
console.table(
  existing.map((r) => ({
    id: r.id,
    name: r.name,
    type: r.type,
    rdata: r.rdata,
    ttl: r.ttl,
  })),
);

// 4) Update existing records by ID
const apexA = existing.find((r) => r.name === '@' && r.type === 'A');
const wwwCname = existing.find((r) => r.name === 'www' && r.type === 'CNAME');

const recordsToUpdate = [];

if (apexA) {
  recordsToUpdate.push({
    id: apexA.id,
    rdata: '198.51.100.42',
    ttl: 300,
  });
}

if (wwwCname) {
  recordsToUpdate.push({
    id: wwwCname.id,
    rdata: 'example.com.',
    ttl: 300,
  });
}

if (recordsToUpdate.length > 0) {
  await client.dnsRecords.updateRecords({
    zoneName,
    records: recordsToUpdate,
  });
}

// 5) Create records that do not exist yet
const recordsToCreate = [];

if (!apexA) {
  recordsToCreate.push({
    name: '@',
    type: 'A',
    rdata: '198.51.100.42',
    ttl: 300,
  });
}

if (!wwwCname) {
  recordsToCreate.push({
    name: 'www',
    type: 'CNAME',
    rdata: 'example.com.',
    ttl: 300,
  });
}

if (recordsToCreate.length > 0) {
  await client.dnsRecords.createRecords({
    zoneName,
    records: recordsToCreate,
  });
}

// 6) Verify final records
const finalRecords = await client.dnsRecords.getRecords({ zoneName });
console.table(
  finalRecords.map((r) => ({
    name: r.name,
    type: r.type,
    rdata: r.rdata,
    ttl: r.ttl,
  })),
);

Notes

  • updateRecords only updates existing records and requires id for each record.
  • Use getRecords first, then build the update payload from returned IDs.
  • Use createRecords for records that do not exist yet.
  • All batch operations are scoped to one zoneName per request.

On this page