User API – Example for DNS Management

We offer an open API for managing DNS records. This is useful if, for example, you want to build your own dynamic DNS or automate updates during SSL renewal via ACME/Let’s Encrypt.

To manage DNS records, use the DNS section of the API. Below is a bash script that demonstrates how this can be done. The script can list, delete, add, and update DNS records for a domain name via simple commands.

Example commands:

List DNS records for a domain name:

./hostup-dns api-testing.test

Add an A record:

• api-testing.test – record name
• A – record type
• 192.168.1.2 – value
• 3600 – TTL
• 0 – priority

./hostup-dns add api-testing.test api-testing.test A 192.168.1.2 3600 0

Update an existing A record:
(note: 14306113 is the record ID, you obtain it via the list command)

./hostup-dns update api-testing.test 14306113 api-testing.test A 192.168.1.2 3600 0

Delete an A record:

./hostup-dns delete api-testing.test 14306113

Install jq:

In order to use the bash script below, you first need to install jq.

brew install jq

brew install jq

apt install jq

apt install jq

Replace USERNAME and PASSWORD in the script below with your login credentials. Alternatively, you can create a separate user with limited rights here:
https://min.hostup.se/profiles/

Bash script:

Copy, save as hostup-dns, and make it executable with chmod +x hostup-dns:

#!/bin/bash

# Authentication details (replace these with your actual credentials)
USERNAME="REPLACEME"
PASSWORD="REPLACEME"

# URL for DNS API
DNS_API_URL="https://min.hostup.se/api/dns"

# Function to display help
display_help() {
    echo "Usage: ./hostup-dns [command] [arguments]"
    echo
    echo "Commands:"
    echo "  --help                  Display this help and exit"
    echo "  no arguments            List all domains with service ID and domain ID"
    echo "  [domain]                List all DNS records for the specified domain"
    echo "  add [domain_name] [record_name] [record_type] [record_content] [record_ttl] [record_priority]"
    echo "                          Add a new DNS record"
    echo "  update [domain_name] [record_id] [record_name] [record_type] [record_content] [record_ttl] [record_priority]"
    echo "                          Update an existing DNS record"
    echo "  delete [domain_name] [record_id]"
    echo "                          Delete a DNS record"
    echo
    echo "Examples:"
    echo "  ./hostup-dns"
    echo "  ./hostup-dns api-testing.test"
    echo "  ./hostup-dns add api-testing.test api-testing.test A 192.168.1.2 3600 0"
    echo "  ./hostup-dns update api-testing.test 14306113 api-testing.test A 192.168.1.2 3600 0"
    echo "  ./hostup-dns delete api-testing.test 14306113"
}

# Function to list domains along with service id and domain id
list_domains() {
    response=$(curl -s -u "$USERNAME:$PASSWORD" "$DNS_API_URL")

    echo "$response" | jq -r '.zones[] | "Domain: \(.name), Service ID: \(.service_id), Domain ID: \(.domain_id)"'
}

# Function to list DNS records for a specific domain
list_dns_records() {
    domain_to_search="$1"
    response=$(curl -s -u "$USERNAME:$PASSWORD" "$DNS_API_URL")
    
    # Find the domain id for the provided domain name
    domain_id=$(echo "$response" | jq -r ".zones[] | select(.name==\"$domain_to_search\") | .domain_id")
    service_id=$(echo "$response" | jq -r ".zones[] | select(.name==\"$domain_to_search\") | .service_id")

    if [ -z "$domain_id" ]; then
        echo "Domain not found or you do not have permission to view its records."
        exit 1
    fi

    # Fetch DNS records for the specific domain
    records_response=$(curl -s -u "$USERNAME:$PASSWORD" "https://min.hostup.se/api/service/$service_id/dns/$domain_id")
    
    echo "$records_response" | jq -r '.records[] | "Record ID: \(.id), Type: \(.type), Name: \(.name), Content: \(.content), TTL: \(.ttl)"'
}

# Function to add a new DNS record
add_dns_record() {
    domain_name="$1"
    record_name="$2"
    record_type="$3"
    record_content="$4"
    record_ttl="$5"
    record_priority="$6"

    response=$(curl -s -u "$USERNAME:$PASSWORD" "$DNS_API_URL")

    domain_id=$(echo "$response" | jq -r ".zones[] | select(.name==\"$domain_name\") | .domain_id")
    service_id=$(echo "$response" | jq -r ".zones[] | select(.name==\"$domain_name\") | .service_id")

    if [ -z "$domain_id" ]; then
        echo "Domain not found or you do not have permission to add records."
        exit 1
    fi

    POST_DATA="$(jq -n \
        --arg name "$record_name" \
        --arg type "$record_type" \
        --argjson ttl "$record_ttl" \
        --argjson priority "$record_priority" \
        --arg content "$record_content" \
        '{name: $name, type: $type, ttl: $ttl, priority: $priority, content: $content}')"

    curl -X POST "https://min.hostup.se/api/service/$service_id/dns/$domain_id/records" \
        -u "$USERNAME:$PASSWORD" \
        -H "Content-Type: application/json" \
        -d "$POST_DATA"
}

# Function to update an existing DNS record
update_dns_record() {
    domain_name="$1"
    record_id="$2"
    record_name="$3"
    record_type="$4"
    record_content="$5"
    record_ttl="$6"
    record_priority="$7"

    response=$(curl -s -u "$USERNAME:$PASSWORD" "$DNS_API_URL")

    domain_id=$(echo "$response" | jq -r ".zones[] | select(.name==\"$domain_name\") | .domain_id")
    service_id=$(echo "$response" | jq -r ".zones[] | select(.name==\"$domain_name\") | .service_id")

    if [ -z "$domain_id" ]; then
        echo "Domain not found or you do not have permission to update records."
        exit 1
    fi

    POST_DATA="$(jq -n \
        --arg name "$record_name" \
        --arg type "$record_type" \
        --argjson ttl "$record_ttl" \
        --argjson priority "$record_priority" \
        --arg content "$record_content" \
        '{name: $name, type: $type, ttl: $ttl, priority: $priority, content: $content}')"

    curl -X PUT "https://min.hostup.se/api/service/$service_id/dns/$domain_id/records/$record_id" \
        -u "$USERNAME:$PASSWORD" \
        -H "Content-Type: application/json" \
        -d "$POST_DATA"
}

# Function to delete a DNS record
delete_dns_record() {
    domain_name="$1"
    record_id="$2"

    response=$(curl -s -u "$USERNAME:$PASSWORD" "$DNS_API_URL")

    domain_id=$(echo "$response" | jq -r ".zones[] | select(.name==\"$domain_name\") | .domain_id")
    service_id=$(echo "$response" | jq -r ".zones[] | select(.name==\"$domain_name\") | .service_id")

    if [ -z "$domain_id" ]; then
        echo "Domain not found or you do not have permission to delete records."
        exit 1
    fi

    curl -X DELETE "https://min.hostup.se/api/service/$service_id/dns/$domain_id/records/$record_id" \
        -u "$USERNAME:$PASSWORD"
}

# Main logic to call the appropriate function based on the arguments passed
if [ "$#" -eq 0 ]; then
    list_domains
elif [ "$1" == "--help" ]; then
    display_help
elif [ "$1" == "add" ]; then
    if [ "$#" -ne 7 ]; then
        echo "Usage: ./hostup-dns add [domain_name] [record_name] [record_type] [record_content] [record_ttl] [record_priority]"
        exit 1
    fi
    add_dns_record "$2" "$3" "$4" "$5" "$6" "$7"
elif [ "$1" == "update" ]; then
    if [ "$#" -ne 8 ]; then
        echo "Usage: ./hostup-dns update [domain_name] [record_id] [record_name] [record_type] [record_content] [record_ttl] [record_priority]"
        exit 1
    fi
    update_dns_record "$2" "$3" "$4" "$5" "$6" "$7" "$8"
elif [ "$1" == "delete" ]; then
    if [ "$#" -ne 3 ]; then
        echo "Usage: ./hostup-dns delete [domain_name] [record_id]"
        exit 1
    fi
    delete_dns_record "$2" "$3"
elif [ "$#" -eq 1 ]; then
    list_dns_records "$1"
else
    echo "Usage: ./hostup-dns [domain] or ./hostup-dns add|update|delete [arguments]"
    exit 1
fi

---