Un token, generado en el panel
Se envía como token portador. Puede limitarlo a solo lectura o a un único servicio si lo desea; los tokens son independientes de su contraseña, y revocar uno nunca cierra su sesión.
Un solo token, y toda la API del panel
JSON sobre HTTPS. No se requiere SDK, ni una cuenta de desarrollador aparte, ni ningún endpoint que exista en el panel pero no aquí.
Crear un servidor
curl -X POST https://api.vpsoffshore.com/v1/servers \
-H "Authorization: Bearer $TOKEN" \
-d '{"plan":"reef","image":"debian-13"}'Devuelve de inmediato un id de despliegue. La máquina responde por SSH unos sesenta segundos después, y la dirección queda enrutada antes de que se envíen las credenciales.
20 endpoints
Todo, en cinco grupos
URL base https://api.vpsoffshore.com/v1. Con versión indicada en la ruta; v1 seguirá funcionando cuando exista v2, y la fecha en la que deje de funcionar se anunciará con un año de antelación.
Servidores
GET
/servers
Todos los servicios de la cuenta, con estado, plan y direcciones.
POST
/servers
Cree uno. Se devuelve de inmediato un identificador de creación; el servidor está accesible aproximadamente un minuto después.
GET
/servers/{id}
Un servicio, incluyendo el uso de recursos en tiempo real durante la última hora.
PATCH
/servers/{id}
Cambiar de plan. Redimensiona sin reconstruir cuando el disco lo permite.
DELETE
/servers/{id}
Destrúyalo. Los discos se conservan 14 días y después se borran antes de reasignarse.
POST
/servers/{id}/actions
reboot · shutdown · start · rebuild · rescue · reset-password.
Almacenamiento
GET
/servers/{id}/snapshots
Instantáneas de un servicio, de la más reciente a la más antigua.
POST
/servers/{id}/snapshots
Cree uno. Es ligero, por lo que es rápido y no duplica el uso de su disco.
POST
/snapshots/{id}/restore
Restaurar en el mismo lugar, o en un servicio distinto del mismo plan o superior.
DELETE
/snapshots/{id}
Elimine una instantánea.
Redes
GET
/servers/{id}/addresses
Direcciones enrutadas a un servicio, v4 y v6.
POST
/servers/{id}/addresses
Solicite una dirección adicional, o un /29.
PUT
/addresses/{ip}/rdns
Configure el DNS inverso. Surte efecto en un minuto, no en la siguiente actualización de zona.
GET
/servers/{id}/bandwidth
Contadores de transferencia. Informativo — no hay ningún límite que superar.
Catálogo
GET
/plans
Todos los planes con su especificación y precio. La misma fuente desde la que se genera este sitio.
GET
/images
Imágenes e ISOs disponibles, incluidas las que usted ha subido.
POST
/images
Suba una ISO mediante URL. Arranca con una consola conectada.
Facturación
GET
/invoices
Facturas, pagadas y pendientes, con la moneda y la transacción en cadena.
POST
/invoices/{id}/pay
Se emite una dirección de pago para una de las 8 monedas aceptadas.
GET
/credits
Créditos de SLA aplicados, junto con el incidente que originó cada uno.
Todo lo que el panel puede hacer está aquí, y nada de lo que hay aquí falta en el panel. Cuando ambos no coinciden, es un error: avísenos desde el panel y se corrige, en lugar de documentarse como comportamiento previsto.
Cómo se comporta
Cuatro decisiones que notará en menos de una hora
Una API se juzga por sus caminos malos, no por los buenos. Tres de los cuatro casos siguientes tratan sobre lo que ocurre cuando algo sale mal.
JSON de entrada, JSON de salida, sin necesidad de SDK
HTTPS simple sin sobre personalizado, sin alternativa XML y sin ritual de firma. Si curl puede hacerlo, usted ya tiene un cliente. Existen bibliotecas oficiales para Go, Python y TypeScript, y ninguna de ellas es obligatoria.
Límites de tasa que no alcanzará por accidente
600 solicitudes por minuto por token, 60 para las llamadas de creación. Cada respuesta incluye el presupuesto restante en una cabecera, y superarlo devuelve 429 con el número de segundos que hay que esperar — nunca un descarte silencioso.
Errores que indican qué hacer
Un 4xx incluye un código legible por máquina, una frase en lenguaje natural y el campo responsable del error. Preferimos devolver un error largo antes que uno breve que haya que adivinar.
Las dos cosas que se escriben una sola vez
Autenticación, y qué aspecto tiene un error
Merece la pena leer ambos antes de escribir la primera llamada, no después del primer fallo.
Autenticar
curl https://api.vpsoffshore.com/v1/servers \
-H "Authorization: Bearer $TOKEN"Los tokens se crean en el panel y pueden limitarse a solo lectura o a un único servicio. Son independientes de su contraseña, y revocar uno no cierra su sesión en ningún sitio.
Consulte el límite de tasa
X-RateLimit-Remaining: 574
X-RateLimit-Reset: 41En todas las respuestas, no solo en la que falla. Superar el límite devuelve un 429 con los segundos de espera, nunca un descarte silencioso ni una respuesta recortada.
Un error le indica el campo
{"error":"plan_unknown",
"message":"No plan named 'reff'. Did you mean 'reef'?",
"field":"plan"}Un código legible por máquina, una frase en lenguaje humano y el campo responsable del fallo. Los errores largos salen más baratos que los cortos que hay que adivinar.
Consultar una configuración
curl https://api.vpsoffshore.com/v1/servers/$ID \
-H "Authorization: Bearer $TOKEN" | jq .statePasa de building a running. No existe ningún webhook que deba registrar antes de poder crear nada, y consultar el estado una vez por segundo está dentro del límite.
Nada que solicitar
El token está en el panel, y el panel se incluye con el primer servidor
Sin cuenta de desarrollador, sin aprobación, sin entorno de pruebas que se comporte de forma distinta a producción.