Getting Started with the DNS Check API

Using the requests library (pip install requests), start a file named getting-started.py with this helper, which sends the key and turns error responses into exceptions. Add each step's code after it, and run it with python getting-started.py:

import os
import time

import requests

API = "https://www.dnscheck.co/api/v2"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['DNSCHECK_API_KEY']}"

def call(method, path, **kwargs):
    response = session.request(method, f"{API}{path}", timeout=30, **kwargs)
    if response.headers.get("Content-Type", "").startswith("application/problem+json"):
        problem = response.json()
        raise RuntimeError(f"{problem['code']}: {problem['detail']} {problem.get('errors', '')}")
    response.raise_for_status()
    return response

For Node.js 18 or later, which has fetch built in, start a file named getting-started.mjs (so top-level await works) with this helper, which sends the key and turns an error response into an exception. Add each step's code after it, and run it with node getting-started.mjs:

import { setTimeout as sleep } from "node:timers/promises";

const API = "https://www.dnscheck.co/api/v2";

// Returns the parsed body, or null for a 204
async function call(method, path, body) {
  const response = await fetch(`${API}${path}`, {
    method,
    headers: {
      Authorization: `Bearer ${process.env.DNSCHECK_API_KEY}`,
      ...(body ? { "Content-Type": "application/json" } : {}),
    },
    body: body ? JSON.stringify(body) : undefined,
    signal: AbortSignal.timeout(30000),
  });
  if (response.headers.get("Content-Type")?.startsWith("application/problem+json")) {
    const problem = await response.json();
    throw new Error(`${problem.code}: ${problem.detail} ${problem.errors ? JSON.stringify(problem.errors) : ""}`);
  }
  if (!response.ok) throw new Error(`HTTP ${response.status} ${response.statusText}`);
  return response.status === 204 ? null : await response.json();
}

Using only the standard library, start a file named getting-started.go with this helper, which sends the key and stops the program with the error if a call fails. Add each step's code inside a main function after it, and run it with go run getting-started.go:

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"os"
	"strings"
	"time"
)

const api = "https://www.dnscheck.co/api/v2"

var client = &http.Client{Timeout: 30 * time.Second}

// Returns the parsed body, or nil for a 204
func call(method, path string, body any) map[string]any {
	var payload bytes.Buffer
	if body != nil {
		if err := json.NewEncoder(&payload).Encode(body); err != nil {
			log.Fatal(err)
		}
	}
	req, err := http.NewRequest(method, api+path, &payload)
	if err != nil {
		log.Fatal(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("DNSCHECK_API_KEY"))
	if body != nil {
		req.Header.Set("Content-Type", "application/json")
	}
	response, err := client.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer response.Body.Close()
	if strings.HasPrefix(response.Header.Get("Content-Type"), "application/problem+json") {
		var problem map[string]any
		if err := json.NewDecoder(response.Body).Decode(&problem); err != nil {
			log.Fatal(err)
		}
		if errors, ok := problem["errors"]; ok {
			log.Fatalf("%v: %v %v", problem["code"], problem["detail"], errors)
		}
		log.Fatalf("%v: %v", problem["code"], problem["detail"])
	}
	if response.StatusCode >= 400 {
		log.Fatalf("HTTP %s", response.Status)
	}
	if response.StatusCode == http.StatusNoContent {
		return nil
	}
	var data map[string]any
	if err := json.NewDecoder(response.Body).Decode(&data); err != nil {
		log.Fatal(err)
	}
	return data
}

group = call(
    "POST", "/record-groups", json={"name": "Mail", "description": "SPF policy"}
).json()
print(group["id"])

const group = await call("POST", "/record-groups", {
  name: "Mail",
  description: "SPF policy",
});
console.log(group.id);

group := call("POST", "/record-groups",
	map[string]any{"name": "Mail", "description": "SPF policy"})
fmt.Println(group["id"])

record = call(
    "POST",
    f"/record-groups/{group['id']}/dns-records",
    json={"name": "example.com", "type": "TXT", "values": ["v=spf1 -all"]},
).json()
print(record["id"], record["status"])

const record = await call("POST", `/record-groups/${group.id}/dns-records`, {
  name: "example.com",
  type: "TXT",
  values: ["v=spf1 -all"],
});
console.log(record.id, record.status);

record := call("POST", fmt.Sprintf("/record-groups/%v/dns-records", group["id"]),
	map[string]any{"name": "example.com", "type": "TXT", "values": []string{"v=spf1 -all"}})
fmt.Println(record["id"], record["status"])

deadline = time.monotonic() + 30
while True:
    time.sleep(5)
    current = call("GET", f"/dns-records/{record['id']}").json()
    if current["checked_at"] or time.monotonic() >= deadline:
        break

if current["checked_at"]:
    print(current["status"], current["error"])
    events = call("GET", f"/dns-records/{record['id']}/events").json()
    for event in events["data"]:
        print(event["timestamp"], event["type"])
else:
    print("The first check hasn't run yet. Try again in a minute.")

const deadline = Date.now() + 30000;
let current;
while (true) {
  await sleep(5000);
  current = await call("GET", `/dns-records/${record.id}`);
  if (current.checked_at || Date.now() >= deadline) break;
}

if (current.checked_at) {
  console.log(current.status, current.error);
  const events = await call("GET", `/dns-records/${record.id}/events`);
  for (const event of events.data) console.log(event.timestamp, event.type);
} else {
  console.log("The first check hasn't run yet. Try again in a minute.");
}

deadline := time.Now().Add(30 * time.Second)
var current map[string]any
for {
	time.Sleep(5 * time.Second)
	current = call("GET", fmt.Sprintf("/dns-records/%v", record["id"]), nil)
	if current["checked_at"] != nil || time.Now().After(deadline) {
		break
	}
}

if current["checked_at"] != nil {
	fmt.Println(current["status"], current["error"])
	events := call("GET", fmt.Sprintf("/dns-records/%v/events", record["id"]), nil)
	for _, item := range events["data"].([]any) {
		event := item.(map[string]any)
		fmt.Println(event["timestamp"], event["type"])
	}
} else {
	fmt.Println("The first check hasn't run yet. Try again in a minute.")
}

call("DELETE", f"/record-groups/{group['id']}")

await call("DELETE", `/record-groups/${group.id}`);

call("DELETE", fmt.Sprintf("/record-groups/%v", group["id"]), nil)