Un SDK marca el límite entre un servicio y las aplicaciones que lo utilizan. Ese límite es más sencillo cuando los objetos describen operaciones útiles y no reflejan la estructura interna del almacenamiento. IaGenify SDK 0.2 aclara esta diferencia para archivos y almacenamiento conectado.
Un archivo es un recurso, no una ruta del servidor
Una aplicación necesita identificar, leer, actualizar o eliminar un archivo. No necesita conocer el directorio de una máquina del servicio donde se guardan sus bytes. El objeto de archivo se centra en su identificador de origen y en las operaciones compatibles.
const file = await api.files.get(sourceId);
console.log(file.sourceId);
file.content = "Revised note";
await file.update();Los identificadores estables hacen que el código sea portable. La misma referencia sirve desde una herramienta local, una interfaz web o una automatización, sin conocer el sistema de archivos del servidor.
El almacenamiento conectado ofrece operaciones útiles
Un recurso de almacenamiento conectado debe permitir que la aplicación lo use. El objeto público expone su identidad y operaciones; no hace falta inspeccionar las credenciales para listar o utilizar el almacenamiento.
const storage = await api.storage.get({ id: storageId });
console.log(storage.id);
const files = await storage.run({ action: "list", path: "/reports" });Así se separan las responsabilidades: la aplicación elige una operación y el servicio utiliza la conexión configurada. El código cliente no necesita copiar sus datos de conexión a su propio estado.
Una interfaz pública más acotada es más fácil de mantener
Si el SDK devuelve detalles internos, las aplicaciones pueden depender de ellos aunque nunca fueran parte del contrato estable. Quitarlos más adelante supondría una ruptura. Los objetos enfocados facilitan documentar y evolucionar el SDK entre runtimes.
No se trata de ocultar funciones útiles, sino de exponerlas en el nivel adecuado: identificadores para localizar recursos, métodos para operaciones admitidas y resultados que la aplicación pueda usar.
El principio de la versión 0.2
IaGenify SDK 0.2 es una versión pequeña con un principio importante: los objetos públicos incluyen lo que la aplicación necesita, sin obligarla a conocer los detalles internos del servicio.
Un SDK fiable ofrece referencias estables y acciones claras mientras el servicio conserva el control de su implementación.
Preguntas frecuentes
¿Por qué usar un identificador en lugar de una ruta de archivo?
El identificador sigue siendo válido entre runtimes y cambios de almacenamiento; una ruta describe una implementación concreta.
¿La aplicación necesita las credenciales del almacenamiento conectado?
El servicio usa la conexión configurada. La aplicación invoca sus operaciones sin copiar credenciales.
¿SDK 0.2 cambia el contenido de los archivos?
No. Aclara las interfaces públicas y las referencias con las que las aplicaciones acceden a ellos.
¿Cuál es el principio general?
Mantener el contrato del SDK centrado en recursos identificables y operaciones compatibles.