Qué es Systemplane
Systemplane no es un servicio independiente. Cada aplicación monta el mismo conjunto de rutas en su propio host y puerto HTTP, bajo un prefijo de ruta específico de la aplicación. El prefijo canónico documentado aquí es
/system, pero varía según la aplicación (consulta la tabla de aplicabilidad más abajo).
Las aplicaciones registran las rutas mediante código, y ningún generador de código las produce. Esta referencia documenta la superficie de forma manual para que puedas operarla de manera consistente entre productos.
Namespaces
La configuración vive en namespaces, cada uno con entradas planas con clave de tipo cadena. Los rieles y los plugins usan tres namespaces canónicos:
El valor de cada entrada no tiene tipo en la capa de transporte. Cada clave registrada acepta su propio escalar, objeto o arreglo JSON, y su propio validador del lado del servidor revisa el valor. No todos los ajustes se pueden cambiar en tiempo de ejecución. La aplicación lee los ajustes de solo arranque una vez, al iniciar. Estos ajustes no aparecen en Systemplane y todavía requieren un reinicio para cambiar.
Endpoints
Todas las rutas son relativas al prefijo de la aplicación (predeterminado
/system).
/system/-/catalog nombra una ruta de metadatos reservada. La aplicación la sirve antes que las rutas de namespace. El segmento - no es un namespace real, y no puedes usarlo como tal. La mayoría de las aplicaciones devuelve los errores en un envelope plano {"code": <int>, "title": "<string>", "message": "<string>"}. Consulta la lista de errores de Systemplane.Autenticación y permisos
La autorización es deny-all de forma predeterminada. Una aplicación sirve la superficie solo después de que configures un autorizador. Sin un autorizador, la aplicación deniega cada solicitud. Cuando habilitas la autenticación, la aplicación aplica control de acceso basado en roles por namespace, sobre una identidad válida. Un plano de plataforma exige una identidad con ámbito de plataforma. En el modo multi-tenant, un plano por tenant, marcado como “(por tenant)” en la tabla de abajo, exige una identidad con ámbito de tenant y lee y escribe solo los valores de ese tenant. Las lecturas requieren el permiso de lectura del namespace y las escrituras requieren el permiso de escritura correspondiente:
La acción de lectura cubre
GET. La acción de escritura cubre PUT y DELETE. Los endpoints de descubrimiento del catálogo requieren permiso de lectura para al menos un namespace.
Las cadenas de permiso exactas pueden variar según la aplicación. Revisa la documentación propia del producto para conocer su modelo de autorización.
Descubrir claves con el catálogo
Cuando una aplicación habilita la superficie de catálogo,
GET /system/-/catalog lista cada clave que registra. La ruta de detalle GET /system/-/catalog/{namespace}/{key} devuelve el contrato de escritura completo de una clave. El contrato cubre su tipo, ámbito de tenant, clase de tiempo de ejecución, esquema JSON, reglas de validación, ejemplos válidos, valor predeterminado y la ruta PUT correspondiente.
Usa el catálogo para saber qué expone un servicio antes de cambiar algo. El catálogo describe el contrato de escritura. Para leer el valor configurado actual, llama a GET /system/{namespace}/{key}.
Qué productos exponen Systemplane
Systemplane es opcional por producto. La siguiente tabla enumera productos que lo montan. Para cada producto indica el prefijo de ruta, el puerto HTTP predeterminado y si el producto también sirve la superficie de descubrimiento del catálogo. El prefijo y el puerto son valores predeterminados. Un despliegue puede sobrescribirlos.