API REST
La API REST convierte tu biblioteca freedam de un lugar que la gente visita en algo a lo que pueden conectarse tus demás sistemas. Tu sitio web puede obtener las imágenes de producto directamente de la fuente de verdad, tus herramientas de producción pueden dejar los archivos terminados de forma automática y, cuando se retoca una imagen, se actualiza en todas partes a la vez, porque todo apunta al mismo recurso.
Qué hace
La API cubre toda la biblioteca y sus direcciones se mantienen estables, de modo que las integraciones que construyas hoy sigan funcionando:
- Recursos: listar, obtener, actualizar y eliminar recursos. Cada recurso tiene un ID público permanente, así que los enlaces a él nunca se rompen.
- Colecciones: crear y gestionar colecciones, añadir y quitar recursos.
- Importaciones: enviar archivos por lotes y consultar su avance hasta que estén totalmente procesados.
- Metadatos: leer las definiciones de tus campos y los términos de vocabulario aprobados, para que tus propias herramientas ofrezcan valores válidos sin tenerlos escritos en el código.
- Enlaces para compartir: crear, actualizar y revocar enlaces para compartir, con contraseñas, fechas de caducidad y permisos de descarga.
- Operaciones: iniciar trabajos grandes (actualizaciones en bloque, eliminaciones en bloque, análisis de IA, exportaciones) y dejar que se ejecuten en segundo plano.
- Webhooks: hacer que freedam avise a tus sistemas cuando ocurra algo, en lugar de que tus sistemas pregunten una y otra vez.
- Videos insertados: generar códigos para insertar recursos de video.
- Consentimientos y tokens: revisar la aceptación de los términos de uso y gestionar el acceso a la API de forma programática.
La API también publica una descripción de sí misma legible por máquinas (una especificación OpenAPI). Es a partir de ella como se construye el SDK de TypeScript oficial, y los desarrolladores pueden usarla para generar un cliente listo para usar en casi cualquier lenguaje de programación.
Cómo funciona
El acceso se controla con tokens. Creas uno en Ajustes → Tokens de API y eliges exactamente lo que puede hacer, por ejemplo leer recursos pero nunca eliminarlos. Cualquier software que tenga ese token puede hacer esas cosas y nada más:
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
https://your-instance.example.com/api/v1/assets
A un token nunca se le puede dar más poder del que tiene la persona que lo creó. Y cuando se rechaza una solicitud, la respuesta indica exactamente qué permiso faltaba, así que solucionarlo es cuestión de consultar, no de adivinar.
Cada solicitud a la API también queda registrada en un registro de auditoría: quién llamó, con qué token, qué hizo y desde dónde. Cada token muestra cuándo y desde dónde se usó por última vez, de modo que un llamante inesperado es fácil de detectar y revocar.
Conviene saber
- Hay límites de velocidad razonables: cada token puede hacer 60 solicitudes por minuto, y las respuestas indican a quien llama cuándo debe ir más despacio. Para trabajos grandes, usa operaciones (una sola solicitud sin importar cuántos recursos afecte) y webhooks en lugar de consultas repetidas.
- Los tokens se muestran una sola vez al crearlos; freedam nunca guarda el token en sí. Revocar uno surte efecto al instante.
- La entrega de imágenes es aparte: las URL de imagen rápidas y sin cookies para tu sitio web tienen su propia sección en la documentación de la API.
- Las instancias autoalojadas tienen la misma API en las mismas direcciones: tus integraciones se van contigo.
El catálogo completo de endpoints y el material de referencia están en la documentación de la API. Si estás valorando una implementación autoalojada y quieres hablarlo, ponte en contacto.