VPS.org API

Documentació de l'API REST

API de instantànies

Gestioneu les instantànies del servidor per a una restauració ràpida en un punt en el temps. Les instantànies capturen l'estat complet del vostre servidor.

Punts finals 4 endpoints
Camí base /api/v1/snapshots
ACONSEGUEIX /api/v1/snapshots/

Llistar totes les instantànies

Recupera una llista de totes les instantànies dels teus servidors.

Paràmetres de consulta

Paràmetre Tipus Obligatori Descripció
server_id integer No Filtra les instantànies per ID del servidor

Exemple de sol·licitud

cURL
Python
JavaScript
curl -X GET "https://admin.vps.org/api/v1/snapshots/?server_id=12345" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
import requests

url = "https://admin.vps.org/api/v1/snapshots/"
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
}
params = {"server_id": 12345}

response = requests.get(url, headers=headers, params=params)
print(response.json())
const response = await fetch('https://admin.vps.org/api/v1/snapshots/?server_id=12345', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  }
});

const snapshots = await response.json();
console.log(snapshots);

Exemple de resposta

{
  "count": 2,
  "results": [
    {
      "id": 801,
      "server": {
        "id": 12345,
        "name": "web-server-01"
      },
      "name": "pre-migration-snapshot",
      "status": "completed",
      "size_mb": 5120,
      "created_at": "2025-01-15T18:30:00Z",
      "description": "Before major migration"
    },
    {
      "id": 798,
      "server": {
        "id": 12345,
        "name": "web-server-01"
      },
      "name": "weekly-snapshot-2025-01-08",
      "status": "completed",
      "size_mb": 4856,
      "created_at": "2025-01-08T12:00:00Z",
      "description": "Weekly snapshot"
    }
  ]
}

Codis d'estat de resposta

200 Llista de captures de pantalla recuperada correctament
401 No autoritzat: testimoni d'autenticació no vàlid o que falta
PUBLICACIÓ /api/v1/snapshots/

Crea una instantània

Create a snapshot of a server's current state. Snapshots are point-in-time copies of the entire server.

Paràmetres del cos de la sol·licitud

Paràmetre Tipus Obligatori Descripció
server_id integer ID del servidor per fer la instantània
name string Nom de la instantània (alfanumèric, guions, subratllats)
description string No Descripció opcional de la instantània

Exemple de sol·licitud

cURL
Python
JavaScript
curl -X POST "https://admin.vps.org/api/v1/snapshots/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": 12345,
    "name": "before-update-snapshot",
    "description": "Snapshot before system update"
  }'
import requests

url = "https://admin.vps.org/api/v1/snapshots/"
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
}
data = {
    "server_id": 12345,
    "name": "before-update-snapshot",
    "description": "Snapshot before system update"
}

response = requests.post(url, headers=headers, json=data)
print(response.json())
const response = await fetch('https://admin.vps.org/api/v1/snapshots/', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    server_id: 12345,
    name: 'before-update-snapshot',
    description: 'Snapshot before system update'
  })
});

const snapshot = await response.json();
console.log(snapshot);

Exemple de resposta

{
  "id": 802,
  "server": {
    "id": 12345,
    "name": "web-server-01"
  },
  "name": "before-update-snapshot",
  "status": "in_progress",
  "size_mb": null,
  "created_at": "2025-01-16T16:15:00Z",
  "description": "Snapshot before system update",
  "message": "Snapshot is being created. This may take 3-10 minutes depending on server size."
}

Codis d'estat de resposta

201 La creació de la instantània s'ha iniciat correctament
400 Bad Request - Invalid parameters or snapshot limit reached
401 No autoritzat: testimoni d'autenticació no vàlid o que falta
404 Not Found - Server does not exist
Nota: You can have a maximum of 5 snapshots per server. Creating a snapshot while the server is running may result in filesystem inconsistencies. For best results, stop the server before creating a snapshot.
PUBLICACIÓ /api/v1/snapshots/{snapshot_id}/restore/

Restaurar des d'una instantània

Restore a server to the state captured in a snapshot. This will overwrite all current data on the server.

Paràmetres de ruta

Paràmetre Tipus Obligatori Descripció
snapshot_id integer ID únic de la instantània

Exemple de sol·licitud

cURL
Python
JavaScript
curl -X POST "https://admin.vps.org/api/v1/snapshots/801/restore/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
import requests

snapshot_id = 801
url = f"https://admin.vps.org/api/v1/snapshots/{snapshot_id}/restore/"
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
}

response = requests.post(url, headers=headers)
print(response.json())
const snapshotId = 801;
const response = await fetch(`https://admin.vps.org/api/v1/snapshots/${snapshotId}/restore/`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  }
});

const result = await response.json();
console.log(result);

Exemple de resposta

{
  "status": "success",
  "message": "Server is being restored from snapshot. This may take 5-15 minutes.",
  "snapshot": {
    "id": 801,
    "name": "pre-migration-snapshot",
    "created_at": "2025-01-15T18:30:00Z"
  },
  "server": {
    "id": 12345,
    "name": "web-server-01",
    "status": "restoring"
  }
}

Codis d'estat de resposta

200 La restauració s'ha iniciat correctament
400 Bad Request - Server is not in a valid state for restoration
401 No autoritzat: testimoni d'autenticació no vàlid o que falta
404 No s'ha trobat: la instantània no existeix.
Avís: Restoring from a snapshot will overwrite all current data on the server. This action cannot be undone. The server will be automatically stopped before restoration begins.
ELIMINAR /api/v1/snapshots/{snapshot_id}/

Suprimeix la instantània

Suprimeix permanentment una instantània. Aquesta acció no es pot desfer.

Paràmetres de ruta

Paràmetre Tipus Obligatori Descripció
snapshot_id integer ID únic de la instantània

Exemple de sol·licitud

cURL
Python
curl -X DELETE "https://admin.vps.org/api/v1/snapshots/801/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
import requests

snapshot_id = 801
url = f"https://admin.vps.org/api/v1/snapshots/{snapshot_id}/"
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
}

response = requests.delete(url, headers=headers)
print(response.status_code)

Codis d'estat de resposta

204 La instantània s'ha suprimit correctament
401 No autoritzat: testimoni d'autenticació no vàlid o que falta
404 No s'ha trobat: la instantània no existeix.

Snapshots vs Backups

Understanding when to use snapshots versus backups:

API de instantànies

  • Propòsit: Quick point-in-time recovery
  • Velocitat: Faster to create and restore (3-15 min)
  • Cas d'ús: Before risky operations (updates, config changes)
  • Emmagatzematge: Stored on same infrastructure
  • Límit: 5 snapshots per server
  • Millor per a: Short-term rollback capability

API de còpies de seguretat

  • Propòsit: Long-term data protection
  • Velocitat: Slower to create and restore (varies)
  • Cas d'ús: Regular automated data protection
  • Emmagatzematge: Separate backup storage
  • Límit: 10 manual + automatic backups
  • Millor per a: Disaster recovery and compliance

Best Practices