Restore Version

​

Endpoint

POST /{collection}/{id}/restore/{v}

​

Path Parameters

​

Authentication

​

Restore Process

1. Pre-restore Snapshot: The current state is saved as a new version with change reason “Pre-restore snapshot”
2. Data Retrieval: The specified version’s data is reconstructed
3. Pre-update Hooks: Executed with action “restore”
4. Document Update: The document is updated with the restored data
5. Post-update Hooks: Executed with action “restore”
6. Audit Logging: The restore action is logged with before/after states
7. New Version: A new version is created with the restored data

​

Response

​

Example Request

curl -X POST "https://api.example.com/employees/emp_12345/restore/2" \
  -H "Authorization: Bearer <token>"

​

Example Response

{
  "_id": "emp_12345",
  "_version": 5,
  "name": "John Doe",
  "email": "[email protected]",
  "department": "Marketing",
  "salary": 75000,
  "created_at": "2024-01-10T09:15:00Z",
  "updated_at": "2024-03-20T16:45:00Z",
  "updated_by": "user_admin"
}

​

Version Timeline Example

Before restore:
Version 1: {name: "John", salary: 70000}
Version 2: {name: "John", salary: 75000}
Version 3: {name: "John Doe", salary: 80000}
Version 4: {name: "John Doe", salary: 85000}  <- current

After restoring to version 2:
Version 1: {name: "John", salary: 70000}
Version 2: {name: "John", salary: 75000}
Version 3: {name: "John Doe", salary: 80000}
Version 4: {name: "John Doe", salary: 85000}
Version 5: {name: "John Doe", salary: 85000}  <- pre-restore snapshot
Version 6: {name: "John", salary: 75000}       <- restored (new current)

​

Important Behaviors

​

Document ID Preservation

​

Metadata Updates

• updated_at: Set to the current timestamp
• updated_by: Set to the user performing the restore

​

Pre-restore Snapshot

​

Hooks Integration

• Action: restore
• Before: Current document state
• After: Restored document data
• Metadata: Includes document_id and restore_version

• Validate the restore operation
• Modify the restored data
• Send notifications
• Trigger external workflows

​

Audit Trail

• Action type: restore
• Before and after document states
• Field-level changes computed
• User who performed the restore
• Success/failure status

​

Error Responses

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid version number",
    "details": {
      "version": "abc"
    }
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}

{
  "error": {
    "code": "FORBIDDEN",
    "message": "You don't have permission to restore this document",
    "details": {
      "action": "restore",
      "collection": "employees"
    }
  }
}

{
  "error": {
    "code": "VERSION_NOT_FOUND",
    "message": "Version not found",
    "details": {
      "collection": "employees",
      "id": "emp_12345",
      "version": 99
    }
  }
}

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Failed to restore document",
    "details": {
      "error": "database connection lost"
    }
  }
}

{
  "error": {
    "code": "VERSIONING_NOT_ENABLED",
    "message": "Versioning is not enabled"
  }
}

​

Permission Requirements

1. Authentication: Valid user credentials
2. Collection-level: restore action permission
3. Document-level: RBAC conditions must pass for the specific document

policies:
  employees:
    admin:
      actions: [read, create, update, delete, restore]
    manager:
      actions: [read, update, restore]
      when: "user.id == resource.manager_id"
    employee:
      actions: [read]
      when: "user.id == resource._id"

​

Use Cases

• Undo Changes: Revert accidental modifications
• Rollback: Return to a known good state after issues
• Data Recovery: Restore deleted or corrupted data
• Compliance: Meet regulatory requirements for data retention
• Testing: Restore to a baseline state for testing
• Comparison: Restore temporarily to compare with current state

​

Best Practices

1. Verify Before Restoring: Use the diff endpoint to review changes before restoring
2. Check Permissions: Ensure users only restore when appropriate
3. Monitor Restores: Log and alert on restore operations for audit purposes
4. Document Reasons: Consider adding a change_reason when possible
5. Test Hooks: Ensure pre/post hooks handle restore actions correctly
6. Backup Strategy: Rely on the pre-restore snapshot as a safety net

​

Notes

• The restored document becomes the new current version
• Previous versions remain intact and accessible
• Field-level policies apply to the returned document
• The restore operation is atomic - either fully succeeds or fails
• Post-restore hooks run asynchronously and are best-effort