API Documentation

This document provides detailed information about the application's RESTful API endpoints. The API is designed to allow programmatic interaction with the DDNS and infrastructure automation platform.

Base URL

The base URL for all API endpoints is /api/v1.

Authentication

Most API endpoints require authentication using JSON Web Tokens (JWT). After successful login (e.g., via /api/v1/auth/token), you will receive a JWT. This token must be included in the Authorization header of subsequent requests as a Bearer token:

Authorization: Bearer <your_jwt_token>

Some specific endpoints, like the DDNS update endpoint, use a dedicated auth_token parameter for simpler client integration.

Endpoints

1. DDNS Update Endpoint

This endpoint is used to update the IP address for a specific hostname. It is designed to be lightweight and compatible with various DDNS clients.

• Endpoint: /api/v1/update

• Method: POST

• Parameters (Form Data or Query Parameters):

  • hostname (string, required): The fully qualified domain name (FQDN) of the host to update (e.g., myhome.ddns.oit.sk).
  • token (string, required): The unique authentication token associated with the hostname. This token is generated when the hostname is created.
  • ip (string, optional): The IP address to set for the hostname. If not provided, the system will attempt to automatically detect the client's public IP address from the request.

• Example Request (using curl):

  curl -X POST \
       "https://ddns.oit.sk/api/v1/update" \
       -d "hostname=myhome.ddns.oit.sk&token=YOUR_HOSTNAME_TOKEN&ip=192.0.2.1"

• Responses:

  • 200 OK (JSON): Update successful or no change needed.

    {
        "status": "success",
        "message": "IP updated successfully."
    }

    or

    {
        "status": "success",
        "message": "IP is already up to date."
    }

  • 400 Bad Request (JSON): Missing required parameters.

    {
        "status": "error",
        "message": "Missing hostname or token parameter."
    }

  • 401 Unauthorized (JSON): Invalid or expired token, or hostname not found.

    {
        "status": "error",
        "message": "Invalid token or hostname not found."
    }

  • 405 Method Not Allowed (JSON): If the request method is not POST.

    {
        "status": "error",
        "message": "Invalid request method."
    }

  • 500 Internal Server Error (JSON): An unexpected error occurred on the server.

    {
        "status": "error",
        "message": "An internal server error occurred during IP update."
    }

2. User Registration Endpoint

This endpoint allows new users to register an account with the platform.

• Endpoint: /api/v1/users/register

• Method: POST

• **Request Body (JSON):

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

  • username (string, required): A unique username for the new account.
  • email (string, required): A unique email address for the new account.
  • password (string, required): The password for the new account.

• Example Request (using curl):

  curl -X POST \
       -H "Content-Type: application/json" \
       -d '{"username": "newuser", "email": "newuser@ddns.oit.sk", "password": "securepassword123"}' \
       "https://ddns.oit.sk/api/v1/users/register"

• Responses:

  • 200 OK (JSON): User registered successfully.

    {
        "status": "success",
        "message": "User registered successfully."
    }

  • 400 Bad Request (JSON): Missing required fields or invalid JSON format.

    {
        "status": "error",
        "message": "Missing required fields: username, email, password."
    }

    or

    {
        "status": "error",
        "message": "Invalid JSON format."
    }

  • 405 Method Not Allowed (JSON): If the request method is not POST.
  • 409 Conflict (JSON): If the username or email already exists.

    {
        "status": "error",
        "message": "User with this username or email already exists."
    }

  • 500 Internal Server Error (JSON): An unexpected error occurred.

3. Authentication Token Endpoint

This endpoint is used to obtain a JSON Web Token (JWT) for authenticating subsequent API requests. The JWT should be included in the Authorization header as a Bearer token.

• Endpoint: /api/v1/auth/token

• Method: POST

• **Request Body (JSON):

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

  • username (string, required): The username of the user.
  • password (string, required): The password of the user.

• Example Request (using curl):

  curl -X POST \
       -H "Content-Type: application/json" \
       -d '{"username": "existinguser", "password": "securepassword123"}' \
       "https://ddns.oit.sk/api/v1/auth/token"

• Responses:

  • 200 OK (JSON): Authentication successful, returns JWT token.

    {
        "status": "success",
        "token": "your_jwt_token_here"
    }

  • 400 Bad Request (JSON): Missing required fields or invalid JSON format.

    {
        "status": "error",
        "message": "Missing required fields: username, password."
    }

    or

    {
        "status": "error",
        "message": "Invalid JSON format."
    }

  • 401 Unauthorized (JSON): Invalid username or password.

    {
        "status": "error",
        "message": "Invalid username or password."
    }

  • 405 Method Not Allowed (JSON): If the request method is not POST.
  • 500 Internal Server Error (JSON): An unexpected error occurred.

4. List Hostnames Endpoint

This endpoint retrieves a list of hostnames associated with the authenticated user.

• Endpoint: /api/v1/hostnames

• Method: GET

• Authentication: Required (JWT in Authorization header)

• Example Request (using curl):

  curl -X GET \
       -H "Authorization: Bearer YOUR_JWT_TOKEN" \
       "https://ddns.oit.sk/api/v1/hostnames"

• Responses:

  • 200 OK (JSON): Success, returns an array of hostname objects.

    {
        "status": "success",
        "data": [
            {
                "id": 1,
                "user_id": 101,
                "subdomain": "mydevice",
                "domain_id": 1,
                "record_type": "A",
                "auth_token": "some_auth_token",
                "last_known_ipv4": "192.0.2.10",
                "last_updated_at": "2023-10-27 10:00:00",
                "is_enabled": true
            },
            // ... more hostname objects
        ]
    }

5. Create Hostname Endpoint

This endpoint allows the authenticated user to create a new hostname.

• Endpoint: /api/v1/hostnames/create

• Method: POST

• Authentication: Required (JWT in Authorization header)

• **Request Body (JSON):

  {
      "subdomain": "string",
      "domain_id": "integer"
  }

  • subdomain (string, required): The subdomain part of the new hostname (e.g., my-new-device).
  • domain_id (integer, required): The ID of the domain under which the hostname will be created.

• Example Request (using curl):

  curl -X POST \
       -H "Content-Type: application/json" \
       -H "Authorization: Bearer YOUR_JWT_TOKEN" \
       -d '{"subdomain": "test-host", "domain_id": 1}' \
       "https://ddns.oit.sk/api/v1/hostnames/create"

• Responses:

  • 201 Created (JSON): Hostname created successfully.

    {
        "status": "success",
        "data": {
            "id": 2,
            "user_id": 101,
            "subdomain": "test-host",
            "domain_id": 1,
            "record_type": "A",
            "auth_token": "new_auth_token",
            "is_enabled": true
        }
    }

  • 400 Bad Request (JSON): Missing required fields.
  • 405 Method Not Allowed (JSON): If the request method is not POST.
  • 500 Internal Server Error (JSON): An unexpected error occurred.

6. Delete Hostname Endpoint

This endpoint allows the authenticated user to delete one of their hostnames.

• Endpoint: /api/v1/hostnames/delete/{id}

• Method: DELETE

• Authentication: Required (JWT in Authorization header)

• Path Parameters:

  • id (integer, required): The ID of the hostname to delete.

• Example Request (using curl):

  curl -X DELETE \
       -H "Authorization: Bearer YOUR_JWT_TOKEN" \
       "https://ddns.oit.sk/api/v1/hostnames/delete/1"

• Responses:

  • 200 OK (JSON): Hostname deleted successfully.

    {
        "status": "success",
        "message": "Hostname deleted successfully."
    }

  • 404 Not Found (JSON): Hostname not found or not owned by the authenticated user.
  • 405 Method Not Allowed (JSON): If the request method is not DELETE.

7. Get Hostname Details Endpoint

This endpoint retrieves detailed information about a specific hostname belonging to the authenticated user.

• Endpoint: /api/v1/hostnames/detail/{id}

• Method: GET

• Authentication: Required (JWT in Authorization header)

• Path Parameters:

  • id (integer, required): The ID of the hostname to retrieve.

• Example Request (using curl):

  curl -X GET \
       -H "Authorization: Bearer YOUR_JWT_TOKEN" \
       "https://ddns.oit.sk/api/v1/hostnames/detail/1"

• Responses:

  • 200 OK (JSON): Success, returns the hostname object.

    {
        "status": "success",
        "data": {
            "id": 1,
            "user_id": 101,
            "subdomain": "mydevice",
            "domain_id": 1,
            "record_type": "A",
            "auth_token": "some_auth_token",
            "last_known_ipv4": "192.0.2.10",
            "last_updated_at": "2023-10-27 10:00:00",
            "is_enabled": true
        }
    }

  • 404 Not Found (JSON): Hostname not found or not owned by the authenticated user.

8. List Targets Endpoint

This endpoint retrieves a list of targets associated with the authenticated user.

• Endpoint: /api/v1/targets

• Method: GET

• Authentication: Required (JWT in Authorization header)

• Example Request (using curl):

  curl -X GET \
       -H "Authorization: Bearer YOUR_JWT_TOKEN" \
       "https://ddns.oit.sk/api/v1/targets"

• Responses:

  • 200 OK (JSON): Success, returns an array of target objects.

    {
        "status": "success",
        "data": [
            {
                "id": 1,
                "user_id": 101,
                "name": "My Firewall",
                "target_type": "HETZNER_FIREWALL",
                "is_healthy": true
            },
            // ... more target objects
        ]
    }

9. Create Target Endpoint

This endpoint allows the authenticated user to create a new target.

• Endpoint: /api/v1/targets/create

• Method: POST

• Authentication: Required (JWT in Authorization header)

• **Request Body (JSON):

  {
      "name": "string",
      "target_type": "string",
      "credentials": {}
  }

  • name (string, required): A user-defined name for the new target (e.g., My Home Firewall).
  • target_type (string, required): The type of the target integration (e.g., HETZNER_FIREWALL, MIKROTIK_ROUTEROS).
  • credentials (object, required): A JSON object containing the necessary credentials for the target. The structure of this object depends on the target_type.

• Example Request (using curl for Hetzner Firewall):

  curl -X POST \
       -H "Content-Type: application/json" \
       -H "Authorization: Bearer YOUR_JWT_TOKEN" \
       -d '{"name": "Hetzner Firewall", "target_type": "HETZNER_FIREWALL", "credentials": {"api_key": "your_hetzner_api_key", "firewall_id": "12345"}}' \
       "https://ddns.oit.sk/api/v1/targets/create"

• Responses:

  • 201 Created (JSON): Target created successfully.

    {
        "status": "success",
        "data": {
            "id": 1
        }
    }

  • 400 Bad Request (JSON): Missing required fields or invalid JSON format.
  • 405 Method Not Allowed (JSON): If the request method is not POST.
  • 500 Internal Server Error (JSON): An unexpected error occurred, possibly due to incorrect credentials format or an issue during target creation.

10. Get Target Details Endpoint

This endpoint retrieves detailed information about a specific target belonging to the authenticated user.

• Endpoint: /api/v1/targets/detail/{id}

• Method: GET

• Authentication: Required (JWT in Authorization header)

• Path Parameters:

  • id (integer, required): The ID of the target to retrieve.

• Example Request (using curl):

  curl -X GET \
       -H "Authorization: Bearer YOUR_JWT_TOKEN" \
       "https://ddns.oit.sk/api/v1/targets/detail/1"

• Responses:

  • 200 OK (JSON): Success, returns the target object.

    {
        "status": "success",
        "data": {
            "id": 1,
            "user_id": 101,
            "name": "My Firewall",
            "target_type": "HETZNER_FIREWALL",
            "is_healthy": true,
            "last_health_check": "2023-10-27 10:00:00"
        }
    }

  • 404 Not Found (JSON): Target not found or not owned by the authenticated user.
  • 500 Internal Server Error (JSON): An unexpected error occurred during retrieval.

11. Delete Target Endpoint

This endpoint allows the authenticated user to delete one of their targets.

• Endpoint: /api/v1/targets/delete/{id}

• Method: DELETE

• Authentication: Required (JWT in Authorization header)

• Path Parameters:

  • id (integer, required): The ID of the target to delete.

• Example Request (using curl):

  curl -X DELETE \
       -H "Authorization: Bearer YOUR_JWT_TOKEN" \
       "https://ddns.oit.sk/api/v1/targets/delete/1"

• Responses:

  • 200 OK (JSON): Target deleted successfully.

    {
        "status": "success",
        "message": "Target deleted successfully."
    }

  • 404 Not Found (JSON): Target not found or not owned by the authenticated user.
  • 405 Method Not Allowed (JSON): If the request method is not DELETE.

12. List Actions Endpoint

This endpoint retrieves a list of actions associated with the authenticated user.

• Endpoint: /api/v1/actions

• Method: GET

• Authentication: Required (JWT in Authorization header)

• Example Request (using curl):

  curl -X GET \
       -H "Authorization: Bearer YOUR_JWT_TOKEN" \
       "https://ddns.oit.sk/api/v1/actions"

• Responses:

  • 200 OK (JSON): Success, returns an array of action objects.

    {
        "status": "success",
        "data": [
            {
                "id": 1,
                "hostname_id": 1,
                "target_id": 1,
                "action_type": "UPDATE_FIREWALL_RULESET",
                "is_enabled": true
            },
            // ... more action objects
        ]
    }

13. Create Action Endpoint

This endpoint allows the authenticated user to create a new action.

• Endpoint: /api/v1/actions/create

• Method: POST

• Authentication: Required (JWT in Authorization header)

• **Request Body (JSON):

  {
      "hostname_id": "integer",
      "target_id": "integer",
      "action_type": "string",
      "params": {}
  }

  • hostname_id (integer, required): The ID of the hostname this action will be associated with.
  • target_id (integer, required): The ID of the target system this action will interact with.
  • action_type (string, required): The type of operation to perform (e.g., UPDATE_FIREWALL_RULESET, CALL_WEBHOOK).
  • params (object, required): A JSON object containing parameters specific to the action_type. For example, for UPDATE_FIREWALL_RULESET, this might include {"ruleset_name": "allow_ssh"}.

• Example Request (using curl):

  curl -X POST \
       -H "Content-Type: application/json" \
       -H "Authorization: Bearer YOUR_JWT_TOKEN" \
       -d '{"hostname_id": 1, "target_id": 1, "action_type": "UPDATE_FIREWALL_RULESET", "params": {"ruleset_name": "my_rules"}}' \
       "https://ddns.oit.sk/api/v1/actions/create"

• Responses:

  • 201 Created (JSON): Action created successfully.

    {
        "status": "success",
        "data": {
            "id": 1
        }
    }

  • 400 Bad Request (JSON): Missing required fields or invalid JSON format.
  • 403 Forbidden (JSON): If the authenticated user does not have permission to associate the hostname or target with this action.
  • 405 Method Not Allowed (JSON): If the request method is not POST.

14. Delete Action Endpoint

This endpoint allows the authenticated user to delete one of their actions.

• Endpoint: /api/v1/actions/delete/{id}

• Method: DELETE

• Authentication: Required (JWT in Authorization header)

• Path Parameters:

  • id (integer, required): The ID of the action to delete.

• Example Request (using curl):

  curl -X DELETE \
        -H "Authorization: Bearer YOUR_JWT_TOKEN" \
        "https://ddns.oit.sk/api/v1/actions/delete/1"

• Responses:

  • 200 OK (JSON): Action deleted successfully.

    {
        "status": "success",
        "message": "Action deleted successfully."
    }

  • 404 Not Found (JSON): Action not found or not owned by the authenticated user.
  • 405 Method Not Allowed (JSON): If the request method is not DELETE.

15. Health Check Endpoint

This endpoint provides basic health check information for the system.

• Endpoint: /api/v1/health

• Method: GET

• Authentication: Not required

• Example Request (using curl):

  curl -X GET "https://ddns.oit.sk/api/v1/health"

• Responses:

  • 200 OK (JSON): System is healthy.

    {
        "status": "healthy",
        "timestamp": "2023-10-27T10:00:00Z",
        "checks": {
            "database": "healthy",
            "cache": "healthy",
            "external_apis": "healthy"
        }
    }

  • 503 Service Unavailable (JSON): System is unhealthy.

16. Detailed Health Check Endpoint

This endpoint provides detailed health check information with system metrics.

• Endpoint: /api/v1/health/detailed

• Method: GET

• Authentication: Not required

• Example Request (using curl):

  curl -X GET "https://ddns.oit.sk/api/v1/health/detailed"

• Responses:

  • 200 OK (JSON): Detailed health information.

    {
        "status": "healthy",
        "timestamp": "2023-10-27T10:00:00Z",
        "checks": {...},
        "metrics": {
            "total_users": 150,
            "active_hostnames": 45,
            "total_actions": 23
        },
        "system": {
            "php_version": "8.2.0",
            "memory_usage": "45MB",
            "uptime": "7 days"
        }
    }

17. Metrics Endpoint

This endpoint provides application metrics for monitoring systems.

• Endpoint: /api/v1/health/metrics

• Method: GET

• Authentication: Not required

• Example Request (using curl):

  curl -X GET "https://ddns.oit.sk/api/v1/health/metrics"

• Responses:

  • 200 OK (JSON): Application metrics.

    {
        "status": "success",
        "metrics": {
            "total_users": 150,
            "active_hostnames": 45,
            "total_actions": 23,
            "ddns_updates_today": 156
        },
        "timestamp": "2023-10-27T10:00:00+00:00"
    }

18. Ping Endpoint

This endpoint provides a simple ping response for load balancers and health checks.

• Endpoint: /api/v1/health/ping

• Method: GET

• Authentication: Not required

• Example Request (using curl):

  curl -X GET "https://ddns.oit.sk/api/v1/health/ping"

• Responses:

  • 200 OK (JSON): Ping response.

    {
        "status": "pong",
        "timestamp": "2023-10-27T10:00:00+00:00",
        "uptime": 604800
    }

19. API Documentation Endpoint

This endpoint serves the API documentation in HTML format.

• Endpoint: /api/v1/documentation

• Method: GET

• Authentication: Not required

• Example Request (using curl):

  curl -X GET "https://ddns.oit.sk/api/v1/documentation"

• Responses:

  • 200 OK (HTML): API documentation page.