API pública
API pública de Blueputto para acceso CRUD autenticado a los registros del espacio de trabajo, con endpoints versionados, claves API, paginación, filtros y acciones de flujo de trabajo.
Grzegorz
La API pública es la capa de integración autenticada de Blueputto. Expone los mismos registros principales con los que la aplicación trabaja cada día, lo que permite a los sistemas externos crear, leer, actualizar y eliminar datos operativos sin introducir un segundo modelo de contenido junto a la interfaz de usuario.
Esta API está disponible en /v1 y está diseñada para funcionar con API Keys a nivel de organización. Eso la convierte en la funcionalidad que usan los equipos cuando los datos de Blueputto necesitan pasar a un sitio web, una automatización, un script de importación, un panel interno u otro sistema de producto.
Una API versionada para los principales recursos del espacio de trabajo
El punto de entrada en /v1 devuelve una carga de descubrimiento compacta con la versión de la API, el formato de autenticación, la URL del documento OpenAPI y la lista de recursos expuestos actualmente.
En la implementación actual, la superficie pública cubre:
documentos,
elementos,
colecciones,
carpetas,
categorías,
estados,
etiquetas,
y plantillas de documentos.
La mayoría de esos recursos admiten el flujo operativo estándar de listar, obtener, crear, actualizar y eliminar. La API también expone acciones específicas del flujo de trabajo cuando la interfaz las necesita, como:
restauración y eliminación permanente para documentos y elementos,
duplicación para documentos,
reordenación para categorías, estados y etiquetas,
y filtrado solo de activos para plantillas de documentos.
Eso es lo que hace que la API pública sea más que una capa de exportación de solo lectura. Refleja de cerca el ciclo de vida real de los registros ya visible en Blueputto.
La autenticación y la forma de las respuestas se mantienen predecibles
La API pública acepta la credencial de la organización en cualquiera de estas dos formas estándar:
x-api-key,
o Authorization: Bearer <key>.
Eso da a los equipos flexibilidad al conectar Blueputto con distintos entornos de ejecución, puertas de enlace y estilos de SDK. La propia clave se crea dentro de la aplicación desde la página de configuración de API Keys.
La forma de las respuestas también es intencionalmente consistente. Las respuestas de un solo recurso se devuelven dentro de un contenedor data. Los endpoints de lista devuelven data junto con meta, que incluye detalles de paginación como page, limit, total items, total pages y el estado de la página siguiente o anterior.
En todo el conjunto actual de recursos, la API también expone filtros prácticos que reflejan flujos reales de la interfaz, incluidos search, deletedOnly, folderId, withoutFolder y activeOnly.
Construida en torno a las mismas reglas operativas que la aplicación
La parte útil de la API pública de Blueputto no es solo que se pueda acceder a los registros externamente. Es que la superficie de integración sigue las mismas reglas que el producto ya aplica en la interfaz.
Por ejemplo, la eliminación de documentos y elementos se modela como un flujo de papelera primero en lugar de una destrucción inmediata. Algunas operaciones de documentos pueden devolver una respuesta de estado bloqueado cuando el registro no se puede editar en ese momento. La limitación de tasa se aplica por clave API, con el límite predeterminado del backend actualmente establecido en 5 req/s por clave.
Eso mantiene la API alineada con el comportamiento real de la aplicación. Las integraciones externas trabajan con el modelo real de recursos de Blueputto, no con un canal lateral simplificado que se comporta de manera diferente al producto.
