starred/nx9-dns-server
1
0
Fork 0
mirror of https://github.com/thakares/nx9-dns-server.git synced 2026-04-27 00:06:00 +03:00
Code Issues Projects Packages Wiki Activity
Page: API Reference
Pages
API Reference Algorithm flowchart Architecture Overview Configuration Reference Contributing Guidelines DNS Record Management DNSSEC Implementation Deployment Options Frequently Asked Questions Home Installation and Setup Roadmap Testing and Diagnostics
1 API Reference
Sunil Purushottam Thakare edited this page 2025-05-09 08:39:01 +05:30
Table of Contents

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": "admin@newdomain.com",
  "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": "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

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:

{
  "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

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": "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

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

{
  "username": "newuser",
  "email": "newuser@example.com",
  "password": "secure-password",
  "role": "viewer"
}

Response:

{
  "id": "3",
  "username": "newuser",
  "email": "newuser@example.com",
  "role": "viewer",
  "created_at": "2025-05-09T18:00:00Z"
}