Colecciones Y Claves

KVNode organiza los datos en colecciones, cada una contiene pares clave-valor. Este documento cubre la gestión de colecciones y las operaciones con claves en detalle.

Gestión de Colecciones

Crear una Colección

1curl -X POST "https://api.hola.cloud/v1/collections" \
2  -H "apikey: tu-api-key" \
3  -H "secret: tu-api-secret" \
4  -d '{"name": "mi-coleccion"}'

Respuesta:

1{"ok":true,"collection":"mi-coleccion"}

Las colecciones se crean al instante. Si la colección ya existe, la operación es idempotente.

Listar Colecciones

1curl "https://api.hola.cloud/v1/collections" \
2  -H "apikey: tu-api-key" \
3  -H "secret: tu-api-secret"

Respuesta:

1{"collections":["mi-coleccion","config","sesiones"]}

Eliminar una Colección

1curl -X DELETE "https://api.hola.cloud/v1/collections/mi-coleccion" \
2  -H "apikey: tu-api-key" \
3  -H "secret: tu-api-secret"

Respuesta:

1{"ok":true,"collection":"mi-coleccion"}

Eliminar una colección borra todas las claves almacenadas en ella. Esta operación no se puede deshacer.

Operaciones con Claves

Las claves de KVNode son cadenas de texto que pueden contener cualquier carácter UTF-8. Los valores deben ser JSON válido.

Establecer una Clave

1curl -X POST "https://api.hola.cloud/v1/collections/mi-coleccion/keys/config:tema" \
2  -H "apikey: tu-api-key" \
3  -H "secret: tu-api-secret" \
4  -d '{"value": {"modo": "oscuro", "tamanoFuente": 14}}'

La respuesta incluye el número de secuencia y la versión:

1{"ok":true,"seq":3,"version":1}

Cada escritura exitosa devuelve un seq (secuencia global) y un version (versión por clave) que aumentan monotónicamente, útiles para control de concurrencia optimista.

Obtener una Clave

1curl "https://api.hola.cloud/v1/collections/mi-coleccion/keys/config:tema" \
2  -H "apikey: tu-api-key" \
3  -H "secret: tu-api-secret"

Respuesta:

1{"key":"config:tema","value":{"modo":"oscuro","tamanoFuente":14},"version":1,"updatedAt":"2025-01-01T00:00:00Z"}

Intentar obtener una clave que no existe devuelve un error 404.

Eliminar una Clave

1curl -X DELETE "https://api.hola.cloud/v1/collections/mi-coleccion/keys/config:tema" \
2  -H "apikey: tu-api-key" \
3  -H "secret: tu-api-secret"

Respuesta:

1{"ok":true,"seq":4,"version":2}

Listar Claves con Prefijo y Límite

1curl "https://api.hola.cloud/v1/collections/mi-coleccion/keys?prefix=config:&limit=20" \
2  -H "apikey: tu-api-key" \
3  -H "secret: tu-api-secret"

Tanto prefix como limit son parámetros de consulta opcionales:

prefix — filtra las claves que comienzan con la cadena indicada
limit — limita la cantidad de registros devueltos (por defecto: sin límite)

Respuesta:

1[
2  {"key":"config:tema","value":{"modo":"oscuro","tamanoFuente":14},"version":1,"updatedAt":"2025-01-01T00:00:00Z"},
3  {"key":"config:idioma","value":"es-ES","version":1,"updatedAt":"2025-01-01T00:00:01Z"}
4]

Convenciones para Nombres de Claves

Aunque KVNode acepta cualquier cadena UTF-8 como clave, recomendamos seguir estas convenciones:

Usa espacios de nombres con dos puntos: app:modulo:clave (ej. config:basedatos:host)
Evita caracteres especiales que puedan interferir con la codificación URL (/, ?, #)
Mantén las claves legibles — los nombres significativos simplifican la depuración
Sé consistente — elige un patrón de nomenclatura y aplícalo en todas las colecciones