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):
http
GET /api/v1/zones
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
To obtain a token:
```http POST /api/v1/auth/login Content-Type: application/json
{ "username": "admin", "password": "your-secure-password" } ```
Response:
json
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expires_at": "2025-06-09T12:00:00Z"
}
Zones Management
List All Zones
http
GET /api/v1/zones
Response:
json
{
"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
```http POST /api/v1/zones Content-Type: application/json
{ "name": "newdomain.com", "admin_email": "admin@newdomain.com", "refresh": 10800, "retry": 3600, "expire": 604800, "minimum": 86400, "default_ttl": 3600 } ```
Response:
json
{
"name": "newdomain.com",
"records_count": 1,
"created_at": "2025-05-09T10:30:00Z",
"updated_at": "2025-05-09T10:30:00Z"
}
Get Zone Details
http
GET /api/v1/zones/example.com
Response:
json
{
"name": "example.com",
"admin_email": "admin@example.com",
"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
```http PUT /api/v1/zones/example.com Content-Type: application/json
{ "admin_email": "dns-admin@example.com", "refresh": 7200, "retry": 1800, "expire": 1209600, "minimum": 43200, "default_ttl": 7200 } ```
Response:
json
{
"name": "example.com",
"admin_email": "dns-admin@example.com",
"refresh": 7200,
"retry": 1800,
"expire": 1209600,
"minimum": 43200,
"default_ttl": 7200,
"updated_at": "2025-05-09T11:45:22Z"
}
Delete a Zone
http
DELETE /api/v1/zones/example.com
Response:
json
{
"success": true,
"message": "Zone 'example.com' deleted successfully"
}
Records Management
List All Records in a Zone
http
GET /api/v1/zones/example.com/records
Response:
json
{
"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
http
GET /api/v1/zones/example.com/records?type=A
Response:
json
{
"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
```http 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:
json
{
"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
http
GET /api/v1/zones/example.com/records/4
Response:
json
{
"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
```http PUT /api/v1/zones/example.com/records/4 Content-Type: application/json
{ "value": "203.0.113.25", "ttl": 7200 } ```
Response:
json
{
"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
http
DELETE /api/v1/zones/example.com/records/4
Response:
json
{
"success": true,
"message": "Record deleted successfully"
}
Bulk Operations
```http 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:
json
{
"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
http
GET /api/v1/zones/example.com/dnssec
Response:
json
{
"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
```http POST /api/v1/zones/example.com/dnssec Content-Type: application/json
{ "enable": true, "algorithm": "RSASHA256", "key_size": 2048 } ```
Response:
json
{
"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
http
POST /api/v1/zones/example.com/dnssec/rotate
Response:
json
{
"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
http
GET /api/v1/users
Response:
json
{
"users": [
{
"id": "1",
"username": "admin",
"email": "admin@example.com",
"role": "administrator",
"created_at": "2025-01-01T00:00:00Z",
"last_login": "2025-05-09T08:15:22Z"
},
{
"id": "2",
"username": "operator",
"email": "operator@example.com",
"role": "operator",
"created_at": "2025-02-15T10:30:00Z",
"last_login": "2025-05-08T14:22:10Z"
}
]
}
Create a New User
```http POST /api/v1/users Content-Type: application/json
{ "username": "newuser", "email": "newuser@example.com", "password": "secure-password", "role": "viewer" } ```
Response:
```json { "id": "3", "username": "newuser", "email": "newuser@example.com", "role": "viewer", "created_at": "2025-05-09T18:00:00Z" }