Skip to content

API Reference Admin API Endpoints Reservation Management Endpoints

Jump to bottom
Jordan edited this page Aug 17, 2026 · 3 revisions

Reservation Management Endpoints

Preserved Qoder snapshot. This deep-dive page is retained so the earlier Wiki work and its source trail are not lost. For the reconciled implementation, Architecture Overview is canonical; references below to retired controllers, listeners, services, or API shapes are historical.

**Referenced Files in This Document** - [api.php](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/routes/api.php) - [AdminReservationController.php](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/Http/Controllers/Api/Admin/AdminReservationController.php) - [EnsureUserIsAdmin.php](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/Http/Middleware/EnsureUserIsAdmin.php) - [ResourceReservationPolicy.php](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/Policies/ResourceReservationPolicy.php) - [ReservationService.php](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/Services/ReservationService.php) - [ResourceReservation.php](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/Models/ResourceReservation.php) - [2025_01_01_000001_create_ptero_resource_reservations_table.php](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/database/migrations/2025_01_01_000001_create_ptero_resource_reservations_table.php) - [2026_04_22_000001_drop_released_from_reservation_status.php](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/database/migrations/2026_04_22_000001_drop_released_from_reservation_status.php) - [AdminApiTest.php](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/tests/Feature/AdminApiTest.php) - [ReservationApiTest.php](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/tests/Feature/ReservationApiTest.php)

Table of Contents

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion
  10. Appendices

Introduction

This document provides comprehensive API documentation for administrative reservation management endpoints that allow administrators to monitor and intervene in the reservation lifecycle. It focuses on:

  • GET /api/dynamic-pterodactyl/admin/reservations: list and filter reservations by status, location, node, user, with pagination.
  • POST /api/dynamic-pterodactyl/admin/reservations/{token}/cancel: cancel a pending reservation with an admin reason.

It also clarifies authentication requirements, error handling patterns, and the distinction between customer-facing operations and administrative intervention capabilities.

Project Structure

The administrative reservation endpoints are defined under the admin route group and implemented via a dedicated controller backed by a service layer. Middleware enforces session-based authentication and admin role checks. Policies provide authorization boundaries for reservation actions.

graph TB
A["Client (Admin UI or Script)"] --> B["API Router<br/>routes/api.php"]
B --> C["Middleware: web, auth, EnsureUserIsAdmin, throttle"]
C --> D["AdminReservationController::index / cancel"]
D --> E["ReservationService"]
E --> F["Database: ptero_resource_reservations"]
Loading

Diagram sources

Section sources

Core Components

  • AdminReservationController: Validates requests, applies filters, paginates results, and cancels reservations.
  • ReservationService: Provides queryAll() for filtering, cancel(), getByToken(), and other lifecycle methods.
  • ResourceReservation model: Defines table mapping, casts, and scopes for pending/expired queries.
  • EnsureUserIsAdmin middleware: Enforces admin access; returns 403 JSON when not authorized.
  • ResourceReservationPolicy: Allows admin bypass for panel users; otherwise restricts actions to owners.

Key responsibilities:

  • Filtering: status, location_id, node_id, user_id.
  • Pagination: per_page parameter defaults to 25, max 100.
  • Cancellation: requires reason string; only pending reservations can be cancelled.

Section sources

Architecture Overview

Administrative endpoints are protected by session-based authentication and an admin role check. Requests flow through middleware before reaching the controller, which delegates to the service layer for data access and business logic. The service uses Eloquent builders for filtering and pagination.

sequenceDiagram
participant Client as "Admin Client"
participant Router as "API Router"
participant MW as "EnsureUserIsAdmin"
participant Ctrl as "AdminReservationController"
participant Svc as "ReservationService"
participant DB as "ptero_resource_reservations"
Client->>Router : GET /admin/reservations?status=...&location_id=...
Router->>MW : Authenticate + Admin check
MW-->>Router : Allow or 403
Router->>Ctrl : index(request)
Ctrl->>Svc : queryAll(filters)
Svc->>DB : SELECT ... ORDER BY created_at DESC, id DESC
DB-->>Svc : Query set
Svc-->>Ctrl : Eloquent builder
Ctrl->>Ctrl : paginate(per_page)
Ctrl-->>Client : { success : true, data : {...} }
Loading

Diagram sources

Detailed Component Analysis

Endpoint: GET /api/dynamic-pterodactyl/admin/reservations

Purpose:

  • List all reservations with optional filters and pagination.

Authentication and Authorization:

  • Requires authenticated session and admin role via EnsureUserIsAdmin middleware.
  • Non-admin users receive 403 JSON response.

Request:

  • Method: GET
  • Path: /api/dynamic-pterodactyl/admin/reservations
  • Query parameters:
    • status: enum[pending, confirmed, cancelled, expired]
    • location_id: integer
    • node_id: integer
    • user_id: integer
    • per_page: integer[1..100], default 25

Response:

  • Success (200):
    • success: boolean
    • data: Laravel paginator object containing:
      • data: array of reservation records
      • per_page: number
      • total, current_page, last_page, etc.

Reservation record fields:

  • id: integer
  • token: string
  • node_id: integer
  • node_name: string|null
  • expires_at: ISO-8601 datetime|null
  • ttl_minutes: integer (remaining minutes while pending)
  • pricing:
    • total: float
    • breakdown: array
    • model: string
  • status: enum[pending, confirmed, cancelled, expired]

Notes:

  • Filters are applied server-side via ReservationService::queryAll().
  • Time range filtering is not supported by this endpoint; use external tools or combine with other endpoints if needed.

Error responses:

  • 403: Admin access required (EnsureUserIsAdmin).
  • 422: Validation errors for invalid query parameters.

Example usage:

  • List pending reservations in a specific location:
    • GET /api/dynamic-pterodactyl/admin/reservations?status=pending&location_id=1
  • Paginate with custom page size:
    • GET /api/dynamic-pterodactyl/admin/reservations?per_page=50

Section sources

Endpoint: POST /api/dynamic-pterodactyl/admin/reservations/{token}/cancel

Purpose:

  • Cancel a pending reservation with an admin-provided reason.

Authentication and Authorization:

  • Requires authenticated session and admin role via EnsureUserIsAdmin middleware.

Request:

  • Method: POST
  • Path: /api/dynamic-pterodactyl/admin/reservations/{token}/cancel
  • Body:
    • reason: string, required, max length 500

Response:

  • Success (200):
    • success: boolean
    • message: "Reservation cancelled"
  • Not Found (404):
    • success: boolean
    • message: "Reservation not found"
  • Conflict (409):
    • success: boolean
    • message: "Only pending reservations can be cancelled (current status: )"
    • Or: "Reservation could not be cancelled because its status changed"
  • Validation Error (422):
    • Missing or invalid reason field

Behavior:

  • Only reservations with status pending can be cancelled.
  • Reason is stored in admin_notes.
  • Audit log entry is created for cancellation.

Edge cases:

  • If the reservation has already transitioned out of pending (e.g., confirmed or expired), cancellation fails with 409.
  • Race conditions where status changes between validation and update result in 409.

Section sources

Data Model: ptero_resource_reservations

Fields relevant to reservations:

  • id: primary key
  • token: unique identifier for tracking
  • cart_item_id: nullable link to cart item
  • service_id: nullable after provisioning
  • user_id: owner of the reservation
  • node_id: assigned node
  • location_id: location context
  • memory: MB
  • cpu: percentage (100 = 1 core)
  • disk: MB
  • calculated_price: decimal(10,2)
  • pricing_breakdown: JSON
  • status: enum[pending, confirmed, expired, cancelled]
  • admin_notes: text
  • expires_at: timestamp
  • timestamps: created_at, updated_at

Indexes:

  • Optimized for node+status+expires_at, cleanup by status+expires_at, location+status, user+status, and created_at.

Status transitions:

  • pending → confirmed | expired | cancelled
  • released was removed; any existing released rows migrated to cancelled.

Section sources

Authentication and Authorization

  • Session-based authentication is enforced by the web and auth middleware.
  • EnsureUserIsAdmin middleware checks that the user has a non-null role; otherwise returns 403 JSON.
  • Policies allow admins (panel users) to bypass ownership checks; otherwise, actions are restricted to the reservation owner.

Practical implications:

  • Customer-facing endpoints do not require admin privileges and enforce ownership policies.
  • Administrative endpoints require explicit admin role and are intended for operational interventions.

Section sources

Error Handling Patterns

Common HTTP status codes:

  • 200: Successful operation
  • 401: Unauthenticated (handled by framework auth)
  • 403: Forbidden (admin access required)
  • 404: Reservation not found
  • 409: Conflict (reservation not in pending state or race condition)
  • 422: Validation error (missing or invalid fields)
  • 429: Rate limit exceeded (throttling applies to admin routes)

Error payloads:

  • Consistent structure with success flag and message for admin endpoints.

Section sources

Dependency Analysis

Administrative endpoints depend on:

  • Route definitions in api.php
  • AdminReservationController for request handling
  • ReservationService for querying and mutating reservations
  • Database schema for persistence
  • Middleware for security and throttling
  • Policies for authorization
graph LR
R["routes/api.php"] --> C["AdminReservationController"]
C --> S["ReservationService"]
S --> M["ResourceReservation (Eloquent)"]
S --> DB["ptero_resource_reservations"]
R --> MW["EnsureUserIsAdmin"]
C --> P["ResourceReservationPolicy"]
Loading

Diagram sources

Section sources

Performance Considerations

  • Throttling: Admin routes are rate-limited at 30 requests per minute to protect backend resources.
  • Pagination: Default per_page is 25; increase up to 100 for large datasets.
  • Indexes: Queries leverage indexes on status, expires_at, location_id, node_id, user_id, and created_at for efficient filtering and ordering.
  • Avoid broad scans: Always apply filters (status, location_id, node_id, user_id) to reduce result sets.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

Common issues and resolutions:

  • 403 Forbidden:
    • Cause: User lacks admin role or is unauthenticated.
    • Resolution: Ensure session is active and user has a panel role.
  • 404 Not Found:
    • Cause: Token does not exist.
    • Resolution: Verify token from listing or logs; ensure correct path.
  • 409 Conflict:
    • Cause: Reservation is not in pending state or status changed during request.
    • Resolution: Re-list reservations to confirm current status; retry if appropriate.
  • 422 Validation Error:
    • Cause: Missing or invalid reason field.
    • Resolution: Provide a valid reason string within length limits.
  • 429 Too Many Requests:
    • Cause: Exceeded throttle limit.
    • Resolution: Back off and retry; consider batching requests.

Operational tips:

  • Use the list endpoint to investigate failed checkouts by filtering status=pending and location_id.
  • For orphaned reservations, filter by expired or cancelled statuses and review admin_notes for context.
  • During maintenance windows, extend TTLs via customer-facing extend endpoint if applicable; administrative cancellation is reserved for problematic cases.

Section sources

Conclusion

The administrative reservation management endpoints provide robust tools for monitoring and intervening in the reservation lifecycle. They enforce strict authentication and authorization, support flexible filtering and pagination, and implement clear error handling patterns. Administrators can efficiently investigate issues, clean up problematic reservations, and maintain system stability during edge cases and maintenance.

[No sources needed since this section summarizes without analyzing specific files]

Appendices

Request/Response Schema Summary

GET /api/dynamic-pterodactyl/admin/reservations

  • Query parameters:
    • status: enum[pending, confirmed, cancelled, expired]
    • location_id: integer
    • node_id: integer
    • user_id: integer
    • per_page: integer[1..100], default 25
  • Response (200):
    • success: boolean
    • data: paginator object with:
      • data: array of reservation objects
      • per_page: number
      • total, current_page, last_page, etc.

POST /api/dynamic-pterodactyl/admin/reservations/{token}/cancel

  • Path parameter:
    • token: string (required)
  • Body:
    • reason: string, required, max length 500
  • Responses:
    • 200: { success: true, message: "Reservation cancelled" }
    • 404: { success: false, message: "Reservation not found" }
    • 409: { success: false, message: "Only pending reservations can be cancelled (current status: )" or "Reservation could not be cancelled because its status changed" }
    • 422: Validation errors

Section sources

Common Administrative Workflows

Investigating failed checkouts:

  • List pending reservations filtered by location_id to identify stuck items.
  • Review expires_at and ttl_minutes to determine urgency.
  • If necessary, cancel with a descriptive reason to free resources.

Cleaning up orphaned reservations:

  • Filter by status=expired or status=cancelled to find stale entries.
  • Inspect admin_notes for context and decide whether to archive or remove.

Handling edge cases during system maintenance:

  • Temporarily extend TTLs via customer-facing extend endpoint if appropriate.
  • Use administrative cancellation for problematic reservations that cannot proceed due to maintenance constraints.

Section sources

Distinction Between Customer-Facing and Administrative Operations

Customer-facing operations:

  • Create, get, cancel, extend reservations via non-admin routes.
  • Enforce ownership policies; users can only act on their own reservations.
  • Do not expose raw node-level details; aggregate per-location maxima only.

Administrative operations:

  • List and cancel reservations across all users.
  • Require admin role; bypass ownership checks via policy.
  • Intended for operational interventions and troubleshooting.

Section sources

DynamicPterodactyl · Dynamic Resource Sliders for Paymenter × Pterodactyl · Reviewed code checkpoint · Publication commits intentionally pin their latest code-bearing predecessor because a Git commit cannot self-reference its unknown object ID.

DynamicPterodactyl

Guides

Architecture

Core Services

API Reference

Database

System

Clone this wiki locally