API Reference - thakares/nx9-dns-server GitHub Wiki

API Reference (Coming Soon)

Note: The API service for nx9-dns-server is currently under development. This page provides a preview of the planned API endpoints and functionality.

API Overview

The nx9-dns-server API is a RESTful service that allows programmatic management of DNS records, zones, and server configuration. It enables automation, integration with other systems, and custom management interfaces.

API Endpoints

The API base URL is: http://<server>:<port>/api/v1/ where <server> is your server address and <port> is the configured API port (default: 8081).

Authentication

All API requests require authentication using JWT (JSON Web Token):

GET /api/v1/zones
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

To obtain a token:

POST /api/v1/auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "your-secure-password"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2025-06-09T12:00:00Z"
}

Zones Management

List All Zones

GET /api/v1/zones

Response:

{
  "zones": [
    {
      "name": "example.com",
      "records_count": 12,
      "created_at": "2025-01-15T08:30:00Z",
      "updated_at": "2025-05-01T14:22:10Z"
    },
    {
      "name": "example.org",
      "records_count": 8,
      "created_at": "2025-03-10T10:15:00Z",
      "updated_at": "2025-04-22T09:45:30Z"
    }
  ]
}

Create a New Zone

POST /api/v1/zones
Content-Type: application/json

{
  "name": "newdomain.com",
  "admin_email": "[email protected]",
  "refresh": 10800,
  "retry": 3600,
  "expire": 604800,
  "minimum": 86400,
  "default_ttl": 3600
}

Response:

{
  "name": "newdomain.com",
  "records_count": 1,
  "created_at": "2025-05-09T10:30:00Z",
  "updated_at": "2025-05-09T10:30:00Z"
}

Get Zone Details

GET /api/v1/zones/example.com

Response:

{
  "name": "example.com",
  "admin_email": "[email protected]",
  "refresh": 10800,
  "retry": 3600,
  "expire": 604800,
  "minimum": 86400,
  "default_ttl": 3600,
  "records_count": 12,
  "created_at": "2025-01-15T08:30:00Z",
  "updated_at": "2025-05-01T14:22:10Z",
  "nameservers": [
    "ns1.example.com",
    "ns2.example.com"
  ],
  "dnssec_enabled": true
}

Update Zone Properties

PUT /api/v1/zones/example.com
Content-Type: application/json

{
  "admin_email": "[email protected]",
  "refresh": 7200,
  "retry": 1800,
  "expire": 1209600,
  "minimum": 43200,
  "default_ttl": 7200
}

Response:

{
  "name": "example.com",
  "admin_email": "[email protected]",
  "refresh": 7200,
  "retry": 1800,
  "expire": 1209600,
  "minimum": 43200,
  "default_ttl": 7200,
  "updated_at": "2025-05-09T11:45:22Z"
}

Delete a Zone

DELETE /api/v1/zones/example.com

Response:

{
  "success": true,
  "message": "Zone 'example.com' deleted successfully"
}

Records Management

List All Records in a Zone

GET /api/v1/zones/example.com/records

Response:

{
  "zone": "example.com",
  "records": [
    {
      "id": "1",
      "domain": "example.com",
      "type": "A",
      "value": "203.0.113.10",
      "ttl": 3600
    },
    {
      "id": "2",
      "domain": "www.example.com",
      "type": "A",
      "value": "203.0.113.10",
      "ttl": 3600
    },
    {
      "id": "3",
      "domain": "example.com",
      "type": "MX",
      "value": "10 mail.example.com",
      "ttl": 3600
    }
  ]
}

Filter Records by Type

GET /api/v1/zones/example.com/records?type=A

Response:

{
  "zone": "example.com",
  "records": [
    {
      "id": "1",
      "domain": "example.com",
      "type": "A",
      "value": "203.0.113.10",
      "ttl": 3600
    },
    {
      "id": "2",
      "domain": "www.example.com",
      "type": "A",
      "value": "203.0.113.10",
      "ttl": 3600
    }
  ]
}

Create a New Record

POST /api/v1/zones/example.com/records
Content-Type: application/json

{
  "domain": "api.example.com",
  "type": "A",
  "value": "203.0.113.20",
  "ttl": 3600
}

Response:

{
  "id": "4",
  "domain": "api.example.com",
  "type": "A",
  "value": "203.0.113.20",
  "ttl": 3600,
  "created_at": "2025-05-09T15:22:45Z"
}

Get Record Details

GET /api/v1/zones/example.com/records/4

Response:

{
  "id": "4",
  "domain": "api.example.com",
  "type": "A",
  "value": "203.0.113.20",
  "ttl": 3600,
  "created_at": "2025-05-09T15:22:45Z",
  "updated_at": "2025-05-09T15:22:45Z"
}

Update a Record

PUT /api/v1/zones/example.com/records/4
Content-Type: application/json

{
  "value": "203.0.113.25",
  "ttl": 7200
}

Response:

{
  "id": "4",
  "domain": "api.example.com",
  "type": "A",
  "value": "203.0.113.25",
  "ttl": 7200,
  "updated_at": "2025-05-09T16:30:10Z"
}

Delete a Record

DELETE /api/v1/zones/example.com/records/4

Response:

{
  "success": true,
  "message": "Record deleted successfully"
}

Bulk Operations

POST /api/v1/zones/example.com/records/batch
Content-Type: application/json

{
  "operations": [
    {
      "operation": "create",
      "domain": "dev.example.com",
      "type": "A",
      "value": "203.0.113.30",
      "ttl": 3600
    },
    {
      "operation": "update",
      "id": "2",
      "value": "203.0.113.10",
      "ttl": 1800
    },
    {
      "operation": "delete",
      "id": "3"
    }
  ]
}

Response:

{
  "success": true,
  "results": [
    {
      "operation": "create",
      "id": "5",
      "status": "success"
    },
    {
      "operation": "update",
      "id": "2",
      "status": "success"
    },
    {
      "operation": "delete",
      "id": "3",
      "status": "success"
    }
  ]
}

DNSSEC Management

Get DNSSEC Status

GET /api/v1/zones/example.com/dnssec

Response:

{
  "enabled": true,
  "keys": [
    {
      "id": "12345",
      "algorithm": "RSASHA256",
      "key_type": "ZSK",
      "bits": 2048,
      "created_at": "2025-01-15T10:00:00Z",
      "expires_at": "2026-01-15T10:00:00Z"
    }
  ],
  "ds_records": [
    {
      "key_tag": "12345",
      "algorithm": "8",
      "digest_type": "2",
      "digest": "A1B2C3D4E5F6..."
    }
  ]
}

Enable DNSSEC for a Zone

POST /api/v1/zones/example.com/dnssec
Content-Type: application/json

{
  "enable": true,
  "algorithm": "RSASHA256",
  "key_size": 2048
}

Response:

{
  "enabled": true,
  "keys": [
    {
      "id": "12345",
      "algorithm": "RSASHA256",
      "key_type": "ZSK",
      "bits": 2048,
      "created_at": "2025-05-09T17:15:30Z",
      "expires_at": "2026-05-09T17:15:30Z"
    }
  ],
  "ds_records": [
    {
      "key_tag": "12345",
      "algorithm": "8",
      "digest_type": "2",
      "digest": "A1B2C3D4E5F6..."
    }
  ]
}

Rotate DNSSEC Keys

POST /api/v1/zones/example.com/dnssec/rotate

Response:

{
  "success": true,
  "message": "DNSSEC key rotation initiated",
  "old_key_id": "12345",
  "new_key_id": "67890",
  "rollover_completion_date": "2025-05-16T17:15:30Z"
}

User Management

List Users

GET /api/v1/users

Response:

{
  "users": [
    {
      "id": "1",
      "username": "admin",
      "email": "[email protected]",
      "role": "administrator",
      "created_at": "2025-01-01T00:00:00Z",
      "last_login": "2025-05-09T08:15:22Z"
    },
    {
      "id": "2",
      "username": "operator",
      "email": "[email protected]",
      "role": "operator",
      "created_at": "2025-02-15T10:30:00Z",
      "last_login": "2025-05-08T14:22:10Z"
    }
  ]
}

Create a New User

POST /api/v1/users
Content-Type: application/json

{
  "username": "newuser",
  "email": "[email protected]",
  "password": "secure-password",
  "role": "viewer"
}

Response:

{
  "id": "3",
  "username": "newuser",
  "email": "[email protected]",
  "role": "viewer",
  "created_at": "2025-05-09T18:00:00Z"
}
⚠️ **GitHub.com Fallback** ⚠️