mirror of https://github.com/freedbygrace/DynamoDNS.git synced 2026-07-26 11:38:13 +00:00

Files

T

alphaeusmote ae19ec9c3d Document project architecture, setup, usage, and API endpoints

Adds comprehensive documentation including architecture, API reference, deployment, development, and user guides with README.md.

Replit-Commit-Author: Agent
Replit-Commit-Session-Id: 9111ef36-26c8-4085-84ca-a35dc1fec1b5
Replit-Commit-Screenshot-Url: https://storage.googleapis.com/screenshot-production-us-central1/7083d608-d6d3-4a6a-9a27-6286c5109627/910f6160-6716-488e-83e6-61256595c269.jpg

2025-05-24 02:16:17 +00:00

10 KiB

Raw Blame History

DynamoDNS API Reference

This document provides detailed information about the DynamoDNS REST API endpoints, request/response formats, and authentication mechanisms.

Authentication

The API supports two authentication methods:

Session Authentication (Web UI)

Used for browser-based interactions. Authenticate via:

POST /api/login
GET /api/user (verify current session)
POST /api/logout

API Token Authentication

Required for programmatic access:

Include the token in the Authorization header: Authorization: Bearer YOUR_API_TOKEN
API tokens can be created and managed through the web interface or via API

API Endpoints

Authentication

`POST /api/login`

Authenticates a user and creates a session.

Request:

{
  "username": "string",
  "password": "string"
}

Response:

{
  "id": "string",
  "username": "string",
  "email": "string",
  "fullName": "string",
  "role": "string"
}

`POST /api/register`

Registers a new user (if enabled).

Request:

{
  "username": "string",
  "email": "string",
  "password": "string",
  "fullName": "string"
}

Response:

{
  "id": "string",
  "username": "string",
  "email": "string",
  "fullName": "string",
  "role": "string"
}

`POST /api/logout`

Ends the current user session.

Response: HTTP 200 OK

`GET /api/user`

Retrieves the current authenticated user's information.

Response:

{
  "id": "string",
  "username": "string", 
  "email": "string",
  "fullName": "string",
  "role": "string"
}

`GET /api/auth/config`

Retrieves the authentication configuration.

Response:

{
  "localAuthEnabled": true,
  "registrationEnabled": false,
  "ldapEnabled": false,
  "oidcEnabled": false
}

Customers

`GET /api/customers`

Returns all customers the authenticated user has access to.

Response:

[
  {
    "id": "string",
    "name": "string",
    "description": "string",
    "email": "string",
    "phone": "string",
    "address": "string",
    "city": "string",
    "state": "string",
    "zipCode": "string",
    "country": "string",
    "website": "string",
    "industry": "string",
    "notes": "string",
    "accountManager": "string",
    "billingEmail": "string",
    "billingAddress": "string",
    "isActive": true,
    "createdAt": "string"
  }
]

`GET /api/customers/:id`

Returns a specific customer by ID.

Response: Customer object

`POST /api/customers`

Creates a new customer.

Request: Customer object without id and createdAt Response: Created customer object

`PUT /api/customers/:id`

Updates an existing customer.

Request: Partial customer object Response: Updated customer object

`DELETE /api/customers/:id`

Deletes a customer.

Response: HTTP 200 OK

Domains

`GET /api/domains`

Returns all domains the user has access to.

Query Parameters:

customerId (optional): Filter by customer ID

Response:

[
  {
    "id": "string",
    "name": "string",
    "customerId": "string",
    "providerId": "string",
    "isActive": true,
    "createdAt": "string",
    "lastUpdated": "string"
  }
]

`GET /api/domains/:id`

Returns a specific domain by ID.

Response: Domain object

`POST /api/domains`

Creates a new domain.

Request:

{
  "name": "string",
  "customerId": "string",
  "providerId": "string",
  "isActive": true
}

Response: Created domain object

`PUT /api/domains/:id`

Updates an existing domain.

Request: Partial domain object Response: Updated domain object

`DELETE /api/domains/:id`

Deletes a domain.

Response: HTTP 200 OK

DNS Records

`GET /api/dns-records`

Returns DNS records the user has access to.

Query Parameters:

domainId (optional): Filter by domain ID

Response:

[
  {
    "id": "string",
    "name": "string",
    "type": "A | AAAA | CNAME | MX | TXT | SRV | NS | CAA | PTR",
    "content": "string",
    "domainId": "string",
    "priority": 0,
    "ttl": 3600,
    "proxied": false,
    "isAutoIP": false,
    "isActive": true,
    "notes": "string",
    "providerRecordId": "string",
    "createdAt": "string",
    "updatedAt": "string",
    "currentIp": "string" // Only present when isAutoIP is true
  }
]

`GET /api/dns-records/:id`

Returns a specific DNS record by ID.

Response: DNS record object

`POST /api/dns-records`

Creates a new DNS record.

Request: DNS record object without id, createdAt, updatedAt Response: Created DNS record object

`PUT /api/dns-records/:id`

Updates an existing DNS record.

Request: Partial DNS record object Response: Updated DNS record object

`DELETE /api/dns-records/:id`

Deletes a DNS record.

Response: HTTP 200 OK

`POST /api/dns-records/:id/toggle`

Toggles a DNS record's active status.

Response: Updated DNS record object

Providers

`GET /api/providers`

Returns all DNS providers.

Response:

[
  {
    "id": "string",
    "name": "string",
    "type": "cloudflare | route53 | godaddy | other",
    "isActive": true,
    "credentials": {
      // Provider-specific credentials (redacted in response)
    },
    "createdAt": "string"
  }
]

`GET /api/providers/:id`

Returns a specific provider by ID.

Response: Provider object (credentials redacted)

`POST /api/providers`

Creates a new provider.

Request: Provider object with credentials Response: Created provider object (credentials redacted)

`PUT /api/providers/:id`

Updates an existing provider.

Request: Partial provider object Response: Updated provider object (credentials redacted)

`DELETE /api/providers/:id`

Deletes a provider.

Response: HTTP 200 OK

DNS History

`GET /api/dns-history`

Returns DNS history records.

Query Parameters:

recordId (optional): Filter by DNS record ID
domainId (optional): Filter by domain ID
startDate (optional): Filter by start date
endDate (optional): Filter by end date

Response:

[
  {
    "id": "string",
    "recordId": "string",
    "domainId": "string",
    "previousValue": "string",
    "newValue": "string",
    "changedBy": "string",
    "createdAt": "string"
  }
]

Metrics

`GET /api/dns-metrics`

Returns DNS metrics.

Query Parameters:

recordId (optional): Filter by DNS record ID
domainId (optional): Filter by domain ID
type (optional): Filter by metric type
startDate (optional): Filter by start date
endDate (optional): Filter by end date

Response:

[
  {
    "id": "string",
    "recordId": "string",
    "domainId": "string",
    "type": "string",
    "value": 0,
    "timestamp": "string"
  }
]

API Tokens

`GET /api/api-tokens`

Returns all API tokens for the authenticated user.

Response:

[
  {
    "id": "string",
    "name": "string",
    "token": "string", // Only the first few and last few characters
    "createdBy": "string",
    "expiresAt": "string",
    "isActive": true,
    "role": "string", 
    "createdAt": "string",
    "customerAccess": [
      {
        "customerId": "string",
        "customerName": "string" // Populated for convenience
      }
    ]
  }
]

`POST /api/api-tokens`

Creates a new API token.

Request:

{
  "name": "string",
  "expiresAt": "string", // optional
  "role": "string",
  "customerIds": ["string"] // optional, if empty, grants access to all customers
}

Response: Created API token object with the full token value (only returned once)

`PUT /api/api-tokens/:id`

Updates an existing API token.

Request:

{
  "name": "string",
  "expiresAt": "string",
  "isActive": true,
  "customerIds": ["string"]
}

Response: Updated API token object

`DELETE /api/api-tokens/:id`

Revokes an API token.

Response: HTTP 200 OK

Webhooks

`GET /api/webhooks`

Returns all webhooks for the authenticated user's customers.

Response:

[
  {
    "id": "string",
    "customerId": "string",
    "name": "string",
    "url": "string",
    "secret": "string", // Redacted
    "events": ["string"],
    "isActive": true,
    "createdAt": "string",
    "lastTriggered": "string"
  }
]

`POST /api/webhooks`

Creates a new webhook.

Request:

{
  "customerId": "string",
  "name": "string",
  "url": "string",
  "secret": "string",
  "events": ["string"],
  "isActive": true
}

Response: Created webhook object (secret redacted)

`GET /api/webhook-logs`

Returns webhook delivery logs.

Query Parameters:

webhookId (required): Filter by webhook ID

Response:

[
  {
    "id": "string",
    "webhookId": "string",
    "event": "string",
    "payload": "object",
    "response": "string",
    "statusCode": 0,
    "success": true,
    "createdAt": "string"
  }
]

Utility Endpoints

`GET /api/public-ip`

Returns the public IP addresses of the client.

Response:

{
  "ipv4": "string",
  "ipv6": "string"
}

Error Responses

All API endpoints return standard HTTP status codes:

400 Bad Request: Invalid input
401 Unauthorized: Missing or invalid authentication
403 Forbidden: Insufficient permissions
404 Not Found: Resource not found
500 Internal Server Error: Server-side error

Error responses include a JSON body with error details:

{
  "message": "Error description",
  "code": "ERROR_CODE",
  "details": {} // Additional error details when available
}

Rate Limiting

API requests are rate-limited to prevent abuse. Rate limit headers are included in all responses:

X-RateLimit-Limit: Number of requests allowed in the current time window
X-RateLimit-Remaining: Number of requests remaining in the current time window
X-RateLimit-Reset: Time when the rate limit window resets (Unix timestamp)

When rate limits are exceeded, a 429 Too Many Requests response is returned.

Pagination

List endpoints support pagination using the following query parameters:

page: Page number (default: 1)
limit: Items per page (default: 20, max: 100)

Paginated responses include metadata:

{
  "data": [],
  "pagination": {
    "total": 0,
    "pages": 0,
    "page": 1,
    "limit": 20
  }
}

10 KiB Raw Blame History

DynamoDNS API Reference

Authentication

Session Authentication (Web UI)

API Token Authentication

API Endpoints

Authentication

POST /api/login

POST /api/register

POST /api/logout

GET /api/user

GET /api/auth/config

Customers

GET /api/customers

GET /api/customers/:id

POST /api/customers

PUT /api/customers/:id

DELETE /api/customers/:id

Domains

GET /api/domains

GET /api/domains/:id

POST /api/domains

PUT /api/domains/:id

DELETE /api/domains/:id

DNS Records

GET /api/dns-records

GET /api/dns-records/:id

POST /api/dns-records

PUT /api/dns-records/:id

DELETE /api/dns-records/:id

POST /api/dns-records/:id/toggle

Providers

GET /api/providers

GET /api/providers/:id

POST /api/providers

PUT /api/providers/:id

DELETE /api/providers/:id

DNS History

GET /api/dns-history

Metrics

GET /api/dns-metrics

API Tokens

GET /api/api-tokens

POST /api/api-tokens

PUT /api/api-tokens/:id

DELETE /api/api-tokens/:id

Webhooks

GET /api/webhooks

POST /api/webhooks

GET /api/webhook-logs

Utility Endpoints

GET /api/public-ip

Error Responses

Rate Limiting

Pagination

10 KiB

Raw Blame History

`POST /api/login`

`POST /api/register`

`POST /api/logout`

`GET /api/user`

`GET /api/auth/config`

`GET /api/customers`

`GET /api/customers/:id`

`POST /api/customers`

`PUT /api/customers/:id`

`DELETE /api/customers/:id`

`GET /api/domains`

`GET /api/domains/:id`

`POST /api/domains`

`PUT /api/domains/:id`

`DELETE /api/domains/:id`

`GET /api/dns-records`

`GET /api/dns-records/:id`

`POST /api/dns-records`

`PUT /api/dns-records/:id`

`DELETE /api/dns-records/:id`

`POST /api/dns-records/:id/toggle`

`GET /api/providers`

`GET /api/providers/:id`

`POST /api/providers`

`PUT /api/providers/:id`

`DELETE /api/providers/:id`

`GET /api/dns-history`

`GET /api/dns-metrics`

`GET /api/api-tokens`

`POST /api/api-tokens`

`PUT /api/api-tokens/:id`

`DELETE /api/api-tokens/:id`

`GET /api/webhooks`

`POST /api/webhooks`

`GET /api/webhook-logs`

`GET /api/public-ip`