Resource Reservations Resource

Resource Reservations

Description

Resource Reservations allow integrations or internal platform systems to reserve access to a resource for a specified time window. This ensures resources (e.g. modules) are not unexpectedly reassigned during critical operations.

Each reservation includes metadata about the reserver, timing, and potential for platform-level overrides or reroutes in exceptional circumstances.

---

Example

Resource Reservation:

{
  "resourceId": "vm_xyz789",
  "reservedBy": "integration_42", // Optional
  "reservedAt": 1722483600000,
  "reservedUntil": 1722487200000,
  "createdAt": 1722483600000,
  "updatedAt": 1722483600000,
  "schemaVersion": 1,
  "violation": {
    "violated": false,
    "violatedAt": 1722483600000, // Optional
    "violatedBy": "admin", // Optional
    "violatedReason": "required module maintenance", // Optional
    "rerouteToResourceId": "3" // Optional
  }
}

---

Create Resource Reservation - (!Project-Betta Platform Admin or Integration!)

POST /resource-reservations

Example Request:

{
  "resourceId": "vm_xyz789",
  "reservedBy": "integration_42", // Optional
  "reservedUntil": 1722487200000
}

Example Response (201 Created):

{
  "success": true,
  "message": "Resource reservation created successfully.",
  "data": {
    "_id": "res_abc123",
    "resourceId": "vm_xyz789",
    "reservedBy": "integration_42",
    "reservedAt": 1722483600000,
    "reservedUntil": 1722487200000,
    "createdAt": 1722483600000,
    "updatedAt": 1722483600000,
    "schemaVersion": 1,
    "violation": {
      "violated": false
    }
  }
}

---

🔌 Integration Guide: Using the Resource Reservation API

Purpose

Integrations should use this endpoint when use of a resource is required for a time window. For example: assigning a module resource to learners within a week

---

🔧 Endpoint

POST /resource-reservations

---

📥 Request Payload

Field	Type	Required	Description
resourceId	string	✅	Unique identifier of the resource to reserve.
reservedBy	string	❌	Optional identifier for the integration (auto-populated if omitted).
reservedUntil	number (ms)	✅	Future timestamp indicating when the reservation expires.

The backend will auto-generate reservedAt, createdAt, updatedAt, and violation fields.

---

🧾 Response Payload

• If successful, you will receive a 201 response with the complete reservation document.

• Reservations can be updated or released later (future endpoint).

---

✅ Best Practices

• Ensure reservedUntil is far enough in the future to account for your operation duration.

---

⚠️ Reservation Violations

In rare cases, the platform may override a reservation if:

• There is a system emergency

• The reservation is stale

• A reroute is required

If a violation occurs:

• violation.violated will be set to true

• You may be notified depending on system configuration

Always be prepared to handle rerouting if violation.rerouteToResourceId is present.